From 23324ae1c7938ba904770fc456d3c07764b9c5e9 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sat, 8 Mar 2008 13:52:38 +0000 Subject: [PATCH] added interface headers with latest discussed changes git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52381 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/Doxyfile.inc | 18 +- interface/aboutdlg.h | 223 ++ interface/accel.h | 140 ++ interface/access.h | 210 ++ interface/animate.h | 296 +++ interface/app.h | 937 ++++++++ interface/apptrait.h | 120 + interface/archive.h | 589 +++++ interface/arrstr.h | 269 +++ interface/artprov.h | 342 +++ interface/atomic.h | 15 + interface/aui/aui.h | 689 ++++++ interface/aui/auibook.h | 342 +++ interface/aui/dockart.h | 143 ++ interface/base64.h | 111 + interface/bitmap.h | 697 ++++++ interface/bmpbuttn.h | 222 ++ interface/bmpcbox.h | 181 ++ interface/brush.h | 333 +++ interface/buffer.h | 112 + interface/busyinfo.h | 73 + interface/button.h | 150 ++ interface/calctrl.h | 373 ++++ interface/caret.h | 155 ++ interface/chartype.h | 47 + interface/checkbox.h | 157 ++ interface/checklst.h | 105 + interface/choicdlg.h | 349 +++ interface/choice.h | 142 ++ interface/choicebk.h | 62 + interface/clipboard.h | 82 + interface/clipbrd.h | 170 ++ interface/clntdata.h | 142 ++ interface/clrpicker.h | 138 ++ interface/cmdline.h | 304 +++ interface/cmdproc.h | 235 ++ interface/cmndata.h | 768 +++++++ interface/collpane.h | 179 ++ interface/colordlg.h | 88 + interface/colour.h | 180 ++ interface/combo.h | 658 ++++++ interface/combobox.h | 306 +++ interface/config.h | 606 +++++ interface/control.h | 62 + interface/convauto.h | 98 + interface/cpp.h | 40 + interface/cshelp.h | 296 +++ interface/ctrlsub.h | 355 +++ interface/cursor.h | 282 +++ interface/dataobj.h | 711 ++++++ interface/dataview.h | 1919 ++++++++++++++++ interface/datectrl.h | 166 ++ interface/dateevt.h | 33 + interface/datetime.h | 1797 +++++++++++++++ interface/datstrm.h | 263 +++ interface/dc.h | 1088 +++++++++ interface/dcbuffer.h | 187 ++ interface/dcclient.h | 105 + interface/dcmemory.h | 72 + interface/dcmirror.h | 35 + interface/dcprint.h | 55 + interface/dcps.h | 145 ++ interface/dcscreen.h | 72 + interface/dcsvg.h | 680 ++++++ interface/dde.h | 337 +++ interface/debug.h | 164 ++ interface/debugrpt.h | 331 +++ interface/defs.h | 149 ++ interface/dialog.h | 559 +++++ interface/dialup.h | 209 ++ interface/dir.h | 268 +++ interface/dirctrl.h | 184 ++ interface/dirdlg.h | 128 ++ interface/display.h | 126 ++ interface/dnd.h | 356 +++ interface/docmdi.h | 154 ++ interface/docview.h | 1536 +++++++++++++ interface/dragimag.h | 218 ++ interface/dynarray.h | 658 ++++++ interface/dynlib.h | 415 ++++ interface/editlbox.h | 95 + interface/encconv.h | 129 ++ interface/event.h | 2857 +++++++++++++++++++++++ interface/fdrepdlg.h | 160 ++ interface/ffile.h | 206 ++ interface/file.h | 336 +++ interface/fileconf.h | 92 + interface/filectrl.h | 223 ++ interface/filedlg.h | 265 +++ interface/filefn.h | 371 +++ interface/filename.h | 987 ++++++++ interface/filepicker.h | 294 +++ interface/filesys.h | 341 +++ interface/font.h | 516 +++++ interface/fontdlg.h | 89 + interface/fontenum.h | 86 + interface/fontmap.h | 179 ++ interface/fontpicker.h | 160 ++ interface/frame.h | 399 ++++ interface/fs_mem.h | 119 + interface/gauge.h | 189 ++ interface/gbsizer.h | 359 +++ interface/gdicmn.h | 822 +++++++ interface/gdiobj.h | 36 + interface/glcanvas.h | 213 ++ interface/graphics.h | 682 ++++++ interface/grid.h | 2858 ++++++++++++++++++++++++ interface/hash.h | 107 + interface/hashmap.h | 105 + interface/hashset.h | 98 + interface/help.h | 267 +++ interface/html/helpctrl.h | 212 ++ interface/html/helpdata.h | 68 + interface/html/helpdlg.h | 82 + interface/html/helpfrm.h | 82 + interface/html/helpwnd.h | 175 ++ interface/html/htmlcell.h | 628 ++++++ interface/html/htmlfilt.h | 43 + interface/html/htmlpars.h | 262 +++ interface/html/htmltag.h | 135 ++ interface/html/htmlwin.h | 464 ++++ interface/html/htmprint.h | 350 +++ interface/html/winpars.h | 314 +++ interface/htmllbox.h | 245 ++ interface/hyperlink.h | 193 ++ interface/icon.h | 252 +++ interface/iconbndl.h | 81 + interface/iconloc.h | 39 + interface/image.h | 1228 ++++++++++ interface/imaglist.h | 198 ++ interface/init.h | 27 + interface/intl.h | 661 ++++++ interface/ipc.h | 357 +++ interface/joystick.h | 273 +++ interface/layout.h | 308 +++ interface/laywin.h | 429 ++++ interface/link.h | 34 + interface/list.h | 367 +++ interface/listbook.h | 57 + interface/listbox.h | 250 +++ interface/listctrl.h | 1496 +++++++++++++ interface/log.h | 793 +++++++ interface/longlong.h | 187 ++ interface/math.h | 16 + interface/mdi.h | 418 ++++ interface/mediactrl.h | 439 ++++ interface/memory.h | 281 +++ interface/menu.h | 835 +++++++ interface/menuitem.h | 296 +++ interface/metafile.h | 151 ++ interface/mimetype.h | 366 +++ interface/minifram.h | 116 + interface/module.h | 128 ++ interface/msgdlg.h | 239 ++ interface/msgqueue.h | 75 + interface/mstream.h | 88 + interface/msw/ole/activex.h | 95 + interface/msw/ole/automtn.h | 206 ++ interface/msw/registry.h | 192 ++ interface/notebook.h | 416 ++++ interface/notifmsg.h | 93 + interface/numdlg.h | 31 + interface/object.h | 610 +++++ interface/odcombo.h | 197 ++ interface/palette.h | 155 ++ interface/panel.h | 139 ++ interface/pen.h | 313 +++ interface/pickerbase.h | 109 + interface/platform.h | 56 + interface/platinfo.h | 246 ++ interface/position.h | 80 + interface/power.h | 38 + interface/print.h | 753 +++++++ interface/printdlg.h | 124 + interface/process.h | 258 +++ interface/progdlg.h | 121 + interface/propdlg.h | 189 ++ interface/protocol/ftp.h | 252 +++ interface/protocol/http.h | 66 + interface/protocol/protocol.h | 123 + interface/ptr_scpd.h | 243 ++ interface/ptr_shrd.h | 85 + interface/quantize.h | 59 + interface/radiobox.h | 318 +++ interface/radiobut.h | 123 + interface/recguard.h | 97 + interface/regex.h | 148 ++ interface/region.h | 277 +++ interface/renderer.h | 381 ++++ interface/richtext/richtextbuffer.h | 1062 +++++++++ interface/richtext/richtextctrl.h | 1443 ++++++++++++ interface/richtext/richtextformatdlg.h | 257 +++ interface/richtext/richtexthtml.h | 112 + interface/richtext/richtextprint.h | 396 ++++ interface/richtext/richtextstyledlg.h | 196 ++ interface/richtext/richtextstyles.h | 673 ++++++ interface/richtext/richtextsymboldlg.h | 198 ++ interface/richtext/richtextxml.h | 102 + interface/sashwin.h | 221 ++ interface/sckipc.h | 307 +++ interface/sckstrm.h | 56 + interface/scopeguard.h | 42 + interface/scrolbar.h | 157 ++ interface/scrolwin.h | 366 +++ interface/settings.h | 493 ++++ interface/sizer.h | 1395 ++++++++++++ interface/slider.h | 290 +++ interface/snglinst.h | 108 + interface/socket.h | 1182 ++++++++++ interface/sound.h | 113 + interface/spinbutt.h | 169 ++ interface/spinctrl.h | 136 ++ interface/splash.h | 88 + interface/splitter.h | 457 ++++ interface/srchctrl.h | 137 ++ interface/sstream.h | 62 + interface/stackwalk.h | 174 ++ interface/statbmp.h | 110 + interface/statbox.h | 88 + interface/statline.h | 87 + interface/stattext.h | 239 ++ interface/statusbr.h | 223 ++ interface/stc/stc.h | 2746 +++++++++++++++++++++++ interface/stdpaths.h | 248 ++ interface/stockitem.h | 29 + interface/stopwatch.h | 96 + interface/strconv.h | 470 ++++ interface/stream.h | 798 +++++++ interface/string.h | 1315 +++++++++++ interface/sysopt.h | 80 + interface/tarstrm.h | 365 +++ interface/taskbar.h | 77 + interface/textctrl.h | 1430 ++++++++++++ interface/textdlg.h | 130 ++ interface/textfile.h | 247 ++ interface/tglbtn.h | 176 ++ interface/thread.h | 1076 +++++++++ interface/timer.h | 189 ++ interface/tipdlg.h | 88 + interface/tipwin.h | 76 + interface/tokenzr.h | 169 ++ interface/toolbar.h | 659 ++++++ interface/toolbook.h | 43 + interface/tooltip.h | 74 + interface/toplevel.h | 385 ++++ interface/tracker.h | 37 + interface/treebase.h | 45 + interface/treebook.h | 268 +++ interface/treectrl.h | 999 +++++++++ interface/txtstrm.h | 270 +++ interface/uri.h | 348 +++ interface/url.h | 143 ++ interface/utils.h | 712 ++++++ interface/valgen.h | 80 + interface/validate.h | 102 + interface/valtext.h | 159 ++ interface/variant.h | 508 +++++ interface/vector.h | 147 ++ interface/vlbox.h | 310 +++ interface/vscroll.h | 887 ++++++++ interface/weakref.h | 123 + interface/wfstream.h | 270 +++ interface/window.h | 2748 +++++++++++++++++++++++ interface/windowid.h | 42 + interface/wizard.h | 510 +++++ interface/wrapsizer.h | 48 + interface/wupdlock.h | 52 + interface/wxcrt.h | 105 + interface/xml/xml.h | 490 ++++ interface/xrc/xmlres.h | 446 ++++ interface/zipstrm.h | 459 ++++ interface/zstream.h | 114 + 272 files changed, 92200 insertions(+), 9 deletions(-) create mode 100644 interface/aboutdlg.h create mode 100644 interface/accel.h create mode 100644 interface/access.h create mode 100644 interface/animate.h create mode 100644 interface/app.h create mode 100644 interface/apptrait.h create mode 100644 interface/archive.h create mode 100644 interface/arrstr.h create mode 100644 interface/artprov.h create mode 100644 interface/atomic.h create mode 100644 interface/aui/aui.h create mode 100644 interface/aui/auibook.h create mode 100644 interface/aui/dockart.h create mode 100644 interface/base64.h create mode 100644 interface/bitmap.h create mode 100644 interface/bmpbuttn.h create mode 100644 interface/bmpcbox.h create mode 100644 interface/brush.h create mode 100644 interface/buffer.h create mode 100644 interface/busyinfo.h create mode 100644 interface/button.h create mode 100644 interface/calctrl.h create mode 100644 interface/caret.h create mode 100644 interface/chartype.h create mode 100644 interface/checkbox.h create mode 100644 interface/checklst.h create mode 100644 interface/choicdlg.h create mode 100644 interface/choice.h create mode 100644 interface/choicebk.h create mode 100644 interface/clipboard.h create mode 100644 interface/clipbrd.h create mode 100644 interface/clntdata.h create mode 100644 interface/clrpicker.h create mode 100644 interface/cmdline.h create mode 100644 interface/cmdproc.h create mode 100644 interface/cmndata.h create mode 100644 interface/collpane.h create mode 100644 interface/colordlg.h create mode 100644 interface/colour.h create mode 100644 interface/combo.h create mode 100644 interface/combobox.h create mode 100644 interface/config.h create mode 100644 interface/control.h create mode 100644 interface/convauto.h create mode 100644 interface/cpp.h create mode 100644 interface/cshelp.h create mode 100644 interface/ctrlsub.h create mode 100644 interface/cursor.h create mode 100644 interface/dataobj.h create mode 100644 interface/dataview.h create mode 100644 interface/datectrl.h create mode 100644 interface/dateevt.h create mode 100644 interface/datetime.h create mode 100644 interface/datstrm.h create mode 100644 interface/dc.h create mode 100644 interface/dcbuffer.h create mode 100644 interface/dcclient.h create mode 100644 interface/dcmemory.h create mode 100644 interface/dcmirror.h create mode 100644 interface/dcprint.h create mode 100644 interface/dcps.h create mode 100644 interface/dcscreen.h create mode 100644 interface/dcsvg.h create mode 100644 interface/dde.h create mode 100644 interface/debug.h create mode 100644 interface/debugrpt.h create mode 100644 interface/defs.h create mode 100644 interface/dialog.h create mode 100644 interface/dialup.h create mode 100644 interface/dir.h create mode 100644 interface/dirctrl.h create mode 100644 interface/dirdlg.h create mode 100644 interface/display.h create mode 100644 interface/dnd.h create mode 100644 interface/docmdi.h create mode 100644 interface/docview.h create mode 100644 interface/dragimag.h create mode 100644 interface/dynarray.h create mode 100644 interface/dynlib.h create mode 100644 interface/editlbox.h create mode 100644 interface/encconv.h create mode 100644 interface/event.h create mode 100644 interface/fdrepdlg.h create mode 100644 interface/ffile.h create mode 100644 interface/file.h create mode 100644 interface/fileconf.h create mode 100644 interface/filectrl.h create mode 100644 interface/filedlg.h create mode 100644 interface/filefn.h create mode 100644 interface/filename.h create mode 100644 interface/filepicker.h create mode 100644 interface/filesys.h create mode 100644 interface/font.h create mode 100644 interface/fontdlg.h create mode 100644 interface/fontenum.h create mode 100644 interface/fontmap.h create mode 100644 interface/fontpicker.h create mode 100644 interface/frame.h create mode 100644 interface/fs_mem.h create mode 100644 interface/gauge.h create mode 100644 interface/gbsizer.h create mode 100644 interface/gdicmn.h create mode 100644 interface/gdiobj.h create mode 100644 interface/glcanvas.h create mode 100644 interface/graphics.h create mode 100644 interface/grid.h create mode 100644 interface/hash.h create mode 100644 interface/hashmap.h create mode 100644 interface/hashset.h create mode 100644 interface/help.h create mode 100644 interface/html/helpctrl.h create mode 100644 interface/html/helpdata.h create mode 100644 interface/html/helpdlg.h create mode 100644 interface/html/helpfrm.h create mode 100644 interface/html/helpwnd.h create mode 100644 interface/html/htmlcell.h create mode 100644 interface/html/htmlfilt.h create mode 100644 interface/html/htmlpars.h create mode 100644 interface/html/htmltag.h create mode 100644 interface/html/htmlwin.h create mode 100644 interface/html/htmprint.h create mode 100644 interface/html/winpars.h create mode 100644 interface/htmllbox.h create mode 100644 interface/hyperlink.h create mode 100644 interface/icon.h create mode 100644 interface/iconbndl.h create mode 100644 interface/iconloc.h create mode 100644 interface/image.h create mode 100644 interface/imaglist.h create mode 100644 interface/init.h create mode 100644 interface/intl.h create mode 100644 interface/ipc.h create mode 100644 interface/joystick.h create mode 100644 interface/layout.h create mode 100644 interface/laywin.h create mode 100644 interface/link.h create mode 100644 interface/list.h create mode 100644 interface/listbook.h create mode 100644 interface/listbox.h create mode 100644 interface/listctrl.h create mode 100644 interface/log.h create mode 100644 interface/longlong.h create mode 100644 interface/math.h create mode 100644 interface/mdi.h create mode 100644 interface/mediactrl.h create mode 100644 interface/memory.h create mode 100644 interface/menu.h create mode 100644 interface/menuitem.h create mode 100644 interface/metafile.h create mode 100644 interface/mimetype.h create mode 100644 interface/minifram.h create mode 100644 interface/module.h create mode 100644 interface/msgdlg.h create mode 100644 interface/msgqueue.h create mode 100644 interface/mstream.h create mode 100644 interface/msw/ole/activex.h create mode 100644 interface/msw/ole/automtn.h create mode 100644 interface/msw/registry.h create mode 100644 interface/notebook.h create mode 100644 interface/notifmsg.h create mode 100644 interface/numdlg.h create mode 100644 interface/object.h create mode 100644 interface/odcombo.h create mode 100644 interface/palette.h create mode 100644 interface/panel.h create mode 100644 interface/pen.h create mode 100644 interface/pickerbase.h create mode 100644 interface/platform.h create mode 100644 interface/platinfo.h create mode 100644 interface/position.h create mode 100644 interface/power.h create mode 100644 interface/print.h create mode 100644 interface/printdlg.h create mode 100644 interface/process.h create mode 100644 interface/progdlg.h create mode 100644 interface/propdlg.h create mode 100644 interface/protocol/ftp.h create mode 100644 interface/protocol/http.h create mode 100644 interface/protocol/protocol.h create mode 100644 interface/ptr_scpd.h create mode 100644 interface/ptr_shrd.h create mode 100644 interface/quantize.h create mode 100644 interface/radiobox.h create mode 100644 interface/radiobut.h create mode 100644 interface/recguard.h create mode 100644 interface/regex.h create mode 100644 interface/region.h create mode 100644 interface/renderer.h create mode 100644 interface/richtext/richtextbuffer.h create mode 100644 interface/richtext/richtextctrl.h create mode 100644 interface/richtext/richtextformatdlg.h create mode 100644 interface/richtext/richtexthtml.h create mode 100644 interface/richtext/richtextprint.h create mode 100644 interface/richtext/richtextstyledlg.h create mode 100644 interface/richtext/richtextstyles.h create mode 100644 interface/richtext/richtextsymboldlg.h create mode 100644 interface/richtext/richtextxml.h create mode 100644 interface/sashwin.h create mode 100644 interface/sckipc.h create mode 100644 interface/sckstrm.h create mode 100644 interface/scopeguard.h create mode 100644 interface/scrolbar.h create mode 100644 interface/scrolwin.h create mode 100644 interface/settings.h create mode 100644 interface/sizer.h create mode 100644 interface/slider.h create mode 100644 interface/snglinst.h create mode 100644 interface/socket.h create mode 100644 interface/sound.h create mode 100644 interface/spinbutt.h create mode 100644 interface/spinctrl.h create mode 100644 interface/splash.h create mode 100644 interface/splitter.h create mode 100644 interface/srchctrl.h create mode 100644 interface/sstream.h create mode 100644 interface/stackwalk.h create mode 100644 interface/statbmp.h create mode 100644 interface/statbox.h create mode 100644 interface/statline.h create mode 100644 interface/stattext.h create mode 100644 interface/statusbr.h create mode 100644 interface/stc/stc.h create mode 100644 interface/stdpaths.h create mode 100644 interface/stockitem.h create mode 100644 interface/stopwatch.h create mode 100644 interface/strconv.h create mode 100644 interface/stream.h create mode 100644 interface/string.h create mode 100644 interface/sysopt.h create mode 100644 interface/tarstrm.h create mode 100644 interface/taskbar.h create mode 100644 interface/textctrl.h create mode 100644 interface/textdlg.h create mode 100644 interface/textfile.h create mode 100644 interface/tglbtn.h create mode 100644 interface/thread.h create mode 100644 interface/timer.h create mode 100644 interface/tipdlg.h create mode 100644 interface/tipwin.h create mode 100644 interface/tokenzr.h create mode 100644 interface/toolbar.h create mode 100644 interface/toolbook.h create mode 100644 interface/tooltip.h create mode 100644 interface/toplevel.h create mode 100644 interface/tracker.h create mode 100644 interface/treebase.h create mode 100644 interface/treebook.h create mode 100644 interface/treectrl.h create mode 100644 interface/txtstrm.h create mode 100644 interface/uri.h create mode 100644 interface/url.h create mode 100644 interface/utils.h create mode 100644 interface/valgen.h create mode 100644 interface/validate.h create mode 100644 interface/valtext.h create mode 100644 interface/variant.h create mode 100644 interface/vector.h create mode 100644 interface/vlbox.h create mode 100644 interface/vscroll.h create mode 100644 interface/weakref.h create mode 100644 interface/wfstream.h create mode 100644 interface/window.h create mode 100644 interface/windowid.h create mode 100644 interface/wizard.h create mode 100644 interface/wrapsizer.h create mode 100644 interface/wupdlock.h create mode 100644 interface/wxcrt.h create mode 100644 interface/xml/xml.h create mode 100644 interface/xrc/xmlres.h create mode 100644 interface/zipstrm.h create mode 100644 interface/zstream.h diff --git a/docs/doxygen/Doxyfile.inc b/docs/doxygen/Doxyfile.inc index 6c72a4082d..2614cf0f02 100644 --- a/docs/doxygen/Doxyfile.inc +++ b/docs/doxygen/Doxyfile.inc @@ -36,7 +36,7 @@ OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO BUILTIN_STL_SUPPORT = NO CPP_CLI_SUPPORT = NO -DISTRIBUTE_GROUP_DOC = NO +DISTRIBUTE_GROUP_DOC = YES SUBGROUPING = YES #--------------------------------------------------------------------------- @@ -65,7 +65,7 @@ ALIASES += endExtraStyleTable="\n" ALIASES += library{1}="\section class_lib Library\n Belongs to library \ref page_libs_\1." ALIASES += nolibrary="\section class_lib Library\n None; this class implementation is entirely header-based." ALIASES += stdobjects="\section class_stdobj Predefined objects\n \b" -ALIASES += category{1}="\section class_category Category\n \1" +ALIASES += category{1}="\section class_category Category\n \ref page_class_cat_\1" # aliases with references to wxWidgets ports ALIASES += nativeimpl{1}="\section class_impl Implementations\n Native implementations are used for \ref page_port_\1 port; generic implementation is used elsewhere." @@ -170,8 +170,8 @@ EXTRACT_STATIC = YES EXTRACT_LOCAL_CLASSES = YES EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = YES -HIDE_UNDOC_MEMBERS = YES -HIDE_UNDOC_CLASSES = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO HIDE_FRIEND_COMPOUNDS = NO HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO @@ -180,7 +180,7 @@ HIDE_SCOPE_NAMES = NO SHOW_INCLUDE_FILES = YES INLINE_INFO = YES SORT_MEMBER_DOCS = YES -SORT_BRIEF_DOCS = YES +SORT_BRIEF_DOCS = NO # don't set it to YES! see http://bugzilla.gnome.org/show_bug.cgi?id=312655 SORT_BY_SCOPE_NAME = NO GENERATE_TODOLIST = YES GENERATE_TESTLIST = YES @@ -192,7 +192,7 @@ ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = YES -SHOW_DIRECTORIES = NO +SHOW_DIRECTORIES = YES FILE_VERSION_FILTER = #--------------------------------------------------------------------------- @@ -200,16 +200,16 @@ FILE_VERSION_FILTER = #--------------------------------------------------------------------------- QUIET = NO WARNINGS = YES -WARN_IF_UNDOCUMENTED = NO +WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO +WARN_NO_PARAMDOC = YES WARN_FORMAT = "$file:$line: $text " WARN_LOGFILE = doxygen.log #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = ./mainpages ./overviews #../../interface +INPUT = ./mainpages ./overviews ../../interface INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.h *.txt RECURSIVE = YES diff --git a/interface/aboutdlg.h b/interface/aboutdlg.h new file mode 100644 index 0000000000..2e36f021da --- /dev/null +++ b/interface/aboutdlg.h @@ -0,0 +1,223 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: aboutdlg.h +// Purpose: documentation for wxAboutDialogInfo class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAboutDialogInfo + @wxheader{aboutdlg.h} + + wxAboutDialogInfo contains information shown in the standard @e About + dialog displayed by the wxAboutBox function. + + This class contains the general information about the program, such as its + name, version, copyright and so on, as well as lists of the program developers, + documentation writers, artists and translators. The simple properties from the + former group are represented as a string with the exception of the program icon + and the program web site, while the lists from the latter group are stored as + wxArrayString and can be either set entirely at once + using wxAboutDialogInfo::SetDevelopers and similar + functions or built one by one using wxAboutDialogInfo::AddDeveloper + etc. + + Please also notice that while all the main platforms have the native + implementation of the about dialog, they are often more limited than the + generic version provided by wxWidgets and so the generic version is used if + wxAboutDialogInfo has any fields not supported by the native version. Currently + GTK+ version supports all the possible fields natively but MSW and Mac versions + don't support URLs, licence text nor custom icons in the about dialog and if + either of those is used, wxAboutBox will automatically + use the generic version so you should avoid specifying these fields to achieve + more native look and feel. + + @library{wxadv} + @category{FIXME} + + @seealso + wxAboutDialogInfo::SetArtists +*/ +class wxAboutDialogInfo +{ +public: + /** + Default constructor leaves all fields are initially uninitialized, in general + you should call at least SetVersion(), + SetCopyright() and + SetDescription(). + */ + wxAboutDialogInfo(); + + /** + Adds an artist name to be shown in the program credits. + + @sa SetArtists() + */ + void AddArtist(const wxString& artist); + + /** + Adds a developer name to be shown in the program credits. + + @sa SetDevelopers() + */ + void AddDeveloper(const wxString& developer); + + /** + Adds a documentation writer name to be shown in the program credits. + + @sa SetDocWriters() + */ + void AddDocWriter(const wxString& docwriter); + + /** + Adds a translator name to be shown in the program credits. Notice that if no + translator names are specified explicitely, wxAboutBox + will try to use the translation of the string @c translator-credits from + the currently used message catalog -- this can be used to show just the name of + the translator of the program in the current language. + + @sa SetTranslators() + */ + void AddTranslator(const wxString& translator); + + /** + Sets the the list of artists to be shown in the program credits. + + @sa AddArtist() + */ + void SetArtists(const wxArrayString& artists); + + /** + Set the short string containing the program copyright information. Notice that + any occurrences of @c "(C)" in @e copyright will be replaced by the + copyright symbol (circled C) automatically, which means that you can avoid + using this symbol in the program source code which can be problematic, + */ + void SetCopyright(const wxString& copyright); + + /** + Set brief, but possibly multiline, description of the program. + */ + void SetDescription(const wxString& desc); + + /** + Set the list of developers of the program. + + @sa AddDeveloper() + */ + void SetDevelopers(const wxArrayString& developers); + + /** + Set the list of documentation writers. + + @sa AddDocWriter() + */ + void SetDocWriters(const wxArrayString& docwriters); + + /** + Set the icon to be shown in the dialog. By default the icon of the main frame + will be shown if the native about dialog supports custom icons. If it doesn't + but a valid icon is specified using this method, the generic about dialog is + used instead so you should avoid calling this function for maximally native + look and feel. + */ + void SetIcon(const wxIcon& icon); + + /** + Set the long, multiline string containing the text of the program licence. + + Only GTK+ version supports showing the licence text in the native about dialog + currently so the generic version will be used under all the other platforms if + this method is called. To preserve the native look and feel it is advised that + you do not call this method but provide a separate menu item in the + @c "Help" menu for displaying the text of your program licence. + */ + void SetLicence(const wxString& licence); + + /** + This is the same as SetLicence(). + */ + void SetLicense(const wxString& licence); + + /** + Set the name of the program. If this method is not called, the string returned + by wxApp::GetAppName will be shown in the dialog. + */ + void SetName(const wxString& name); + + /** + Set the list of translators. Please see + AddTranslator() for additional + discussion. + */ + void SetTranslators(const wxArrayString& translators); + + /** + Set the version of the program. The version is in free format, i.e. not + necessarily in the @c x.y.z form but it shouldn't contain the "version" + word. + */ + void SetVersion(const wxString& version); + + /** + Set the web site for the program and its description (which defaults to URL + itself if empty). + + Please notice that only GTK+ version currently supports showing the link in the + native about dialog so if this method is called, the generic version will be + used under all the other platforms. + */ + void SetWebSite(const wxString& url, + const wxString& desc = wxEmptyString); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + This function shows the standard about dialog containing the information + specified in @e info. If the current platform has a native about dialog + which is capable of showing all the fields in @e info, the native dialog is + used, otherwise the function falls back to the generic wxWidgets version of the + dialog, i.e. does the same thing as wxGenericAboutBox. + + Here is an example of how this function may be used: + + @code + void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event)) + { + wxAboutDialogInfo info; + info.SetName(_("My Program")); + info.SetVersion(_("1.2.3 Beta")); + info.SetDescription(_("This program does something great.")); + info.SetCopyright(_T("(C) 2007 Me my@email.addre.ss")); + + wxAboutBox(info); + } + @endcode + + Please see the @ref overview_sampledialogs "dialogs sample" for more examples of + using this function and wxAboutDialogInfo for the + description of the information which can be shown in the about dialog. +*/ +void wxAboutBox(const wxAboutDialogInfo& info); + +/** + This function does the same thing as wxAboutBox except + that it always uses the generic wxWidgets version of the dialog instead of the + native one. This is mainly useful if you need to customize the dialog by e.g. + adding custom controls to it (customizing the native dialog is not currently + supported). + + See the @ref overview_sampledialogs "dialogs sample" for an example of about + dialog + customization. + + @sa wxAboutDialogInfo +*/ +void wxGenericAboutBox(const wxAboutDialogInfo& info); + diff --git a/interface/accel.h b/interface/accel.h new file mode 100644 index 0000000000..5ae1b3f4e2 --- /dev/null +++ b/interface/accel.h @@ -0,0 +1,140 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: accel.h +// Purpose: documentation for wxAcceleratorEntry class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAcceleratorEntry + @wxheader{accel.h} + + An object used by an application wishing to create an @ref + overview_wxacceleratortable "accelerator table". + + @library{wxcore} + @category{FIXME} + + @seealso + wxAcceleratorTable, wxWindow::SetAcceleratorTable +*/ +class wxAcceleratorEntry +{ +public: + //@{ + /** + Constructor. + + @param flags + One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. Indicates + which modifier key is held down. + + @param keyCode + The keycode to be detected. See Keycodes for a full list of keycodes. + + @param cmd + The menu or control command identifier. + */ + wxAcceleratorEntry(); + wxAcceleratorEntry(int flags, int keyCode, int cmd); + //@} + + /** + Returns the command identifier for the accelerator table entry. + */ + int GetCommand(); + + /** + Returns the flags for the accelerator table entry. + */ + int GetFlags(); + + /** + Returns the keycode for the accelerator table entry. + */ + int GetKeyCode(); + + /** + Sets the accelerator entry parameters. + + @param flags + One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. Indicates + which modifier key is held down. + + @param keyCode + The keycode to be detected. See Keycodes for a full list of keycodes. + + @param cmd + The menu or control command identifier. + */ +#define void Set(int flags, int keyCode, int cmd) /* implementation is private */ +}; + + +/** + @class wxAcceleratorTable + @wxheader{accel.h} + + An accelerator table allows the application to specify a table of keyboard + shortcuts for + menus or other commands. On Windows and Mac OS X, menu or button commands are + supported; on GTK, + only menu commands are supported. + + The object @b wxNullAcceleratorTable is defined to be a table with no data, and + is the + initial accelerator table for a window. + + @library{wxcore} + @category{misc} + + @stdobjects + Objects: + wxNullAcceleratorTable + + @seealso + wxAcceleratorEntry, wxWindow::SetAcceleratorTable +*/ +class wxAcceleratorTable : public wxObject +{ +public: + //@{ + /** + Loads the accelerator table from a Windows resource (Windows only). + + @param n + Number of accelerator entries. + + @param entries + The array of entries. + + @param resource + Name of a Windows accelerator. + */ + wxAcceleratorTable(); + wxAcceleratorTable(const wxAcceleratorTable& bitmap); + wxAcceleratorTable(int n, wxAcceleratorEntry entries[]); + wxAcceleratorTable(const wxString& resource); + //@} + + /** + Destroys the wxAcceleratorTable object. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxAcceleratorTable(); + + /** + Returns @true if the accelerator table is valid. + */ +#define bool IsOk() /* implementation is private */ + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + + @param accel + Accelerator table to assign. + */ + wxAcceleratorTable operator =(const wxAcceleratorTable& accel); +}; diff --git a/interface/access.h b/interface/access.h new file mode 100644 index 0000000000..d2aa61a9b9 --- /dev/null +++ b/interface/access.h @@ -0,0 +1,210 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: access.h +// Purpose: documentation for wxAccessible class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAccessible + @wxheader{access.h} + + The wxAccessible class allows wxWidgets applications, and + wxWidgets itself, to return extended information about user interface elements + to client applications such as screen readers. This is the + main way in which wxWidgets implements accessibility features. + + At present, only Microsoft Active Accessibility is supported + by this class. + + To use this class, derive from wxAccessible, implement appropriate + functions, and associate an object of the class with a + window using wxWindow::SetAccessible. + + All functions return an indication of success, failure, or not implemented + using values of the wxAccStatus enum type. + + If you return 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 @e 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. + + @library{wxcore} + @category{FIXME} +*/ +class wxAccessible : public wxObject +{ +public: + /** + Constructor, taking an optional window. The object can be associated with + a window later. + */ + wxAccessible(wxWindow* win = @NULL); + + /** + Destructor. + */ + ~wxAccessible(); + + /** + Performs the default action for the object. @e childId is 0 (the action for + this object) + or greater than 0 (the action for a child). Return wxACC_NOT_SUPPORTED if there + is no default action for this window (e.g. an edit control). + */ + virtual wxAccStatus DoDefaultAction(int childId); + + /** + Gets the specified child (starting from 1). If @e child is @NULL and the return + value is wxACC_OK, + this means that the child is a simple element and not an accessible object. + */ + virtual wxAccStatus GetChild(int childId, wxAccessible** child); + + /** + Returns the number of children in @e childCount. + */ + virtual wxAccStatus GetChildCount(int* childCount); + + /** + Gets the default action for this object (0) or a child (greater than 0). + Return wxACC_OK even if there is no action. @e actionName is the action, or the + empty + string if there is no action. The retrieved string describes the action that is + performed on an object, + not what the object does as a result. For example, a toolbar button that prints + a document has a default action of "Press" rather than "Prints the current + document." + */ + virtual wxAccStatus GetDefaultAction(int childId, + wxString* actionName); + + /** + Returns the description for this object or a child. + */ + virtual wxAccStatus GetDescription(int childId, + wxString* description); + + /** + Gets the window with the keyboard focus. If childId is 0 and child is @NULL, no + object in + this subhierarchy has the focus. If this object has the focus, child should be + 'this'. + */ + virtual wxAccStatus GetFocus(int* childId, wxAccessible** child); + + /** + Returns help text for this object or a child, similar to tooltip text. + */ + virtual wxAccStatus GetHelpText(int childId, wxString* helpText); + + /** + Returns the keyboard shortcut for this object or child. + Return e.g. ALT+K. + */ + virtual wxAccStatus GetKeyboardShortcut(int childId, + wxString* shortcut); + + /** + Returns the rectangle for this object (id is 0) or a child element (id is + greater than 0). + @e rect is in screen coordinates. + */ + virtual wxAccStatus GetLocation(wxRect& rect, int elementId); + + /** + Gets the name of the specified object. + */ + virtual wxAccStatus GetName(int childId, wxString* name); + + /** + Returns the parent of this object, or @NULL. + */ + virtual wxAccStatus GetParent(wxAccessible** parent); + + /** + Returns a role constant describing this object. See wxAccessible for a list + of these roles. + */ + virtual wxAccStatus GetRole(int childId, wxAccRole* role); + + /** + Gets a variant representing the selected children + of this object. + + Acceptable values are: + + a null variant (IsNull() returns TRUE) + a list variant (GetType() == wxT("list")) + an integer representing the selected child element, + or 0 if this object is selected (GetType() == wxT("long")) + a "void*" pointer to a wxAccessible child object + */ + virtual wxAccStatus GetSelections(wxVariant* selections); + + /** + Returns a state constant. See wxAccessible for a list + of these states. + */ + virtual wxAccStatus GetState(int childId, long* state); + + /** + Returns a localized string representing the value for the object + or child. + */ + virtual wxAccStatus GetValue(int childId, wxString* strValue); + + /** + Returns the window associated with this object. + */ + wxWindow* GetWindow(); + + /** + Returns a status value and object id to indicate whether the given point was on + this or + a child object. Can return either a child object, or an integer + representing the child element, starting from 1. + + @e pt is in screen coordinates. + */ + virtual wxAccStatus HitTest(const wxPoint& pt, int* childId, + wxAccessible** childObject); + + /** + Navigates from @e fromId to @e toId/@e toObject. + */ + virtual wxAccStatus Navigate(wxNavDir navDir, int fromId, + int* toId, + wxAccessible** toObject); + + /** + Allows the application to send an event when something changes in an accessible + object. + */ + virtual static void NotifyEvent(int eventType, wxWindow* window, + wxAccObject objectType, + int objectType); + + /** + Selects the object or child. See wxAccessible for a list + of the selection actions. + */ + virtual wxAccStatus Select(int childId, + wxAccSelectionFlags selectFlags); + + /** + Sets the window associated with this object. + */ + void SetWindow(wxWindow* window); +}; diff --git a/interface/animate.h b/interface/animate.h new file mode 100644 index 0000000000..471271b675 --- /dev/null +++ b/interface/animate.h @@ -0,0 +1,296 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: animate.h +// Purpose: documentation for wxAnimationCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAnimationCtrl + @wxheader{animate.h} + + This is a static control which displays an animation. + wxAnimationCtrl API is simple as possible and won't give you full control on the + animation; if you need it then use wxMediaCtrl. + + This control is useful to display a (small) animation while doing a long task + (e.g. a "throbber"). + + It is only available if @c wxUSE_ANIMATIONCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxAC_DEFAULT_STYLE}: + The default style: wxBORDER_NONE. + @style{wxAC_NO_AUTORESIZE}: + By default, the control will adjust its size to exactly fit to the + size of the animation when SetAnimation is called. If this style + flag is given, the control will not change its size + @endStyleTable + + @library{wxadv} + @category{ctrl} + @appearance{animationctrl.png} + + @seealso + wxAnimation +*/ +class wxAnimationCtrl : public wxControl +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxAnimationCtrl(wxWindow * parent, wxWindowID id, + const wxAnimation& anim, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxAC_DEFAULT_STYLE, + const wxString& name = "animationctrl"); + + /** + After control creation you must explicitely call Play() + to start to play the animation. Until that function won't be called, the first + frame + of the animation is displayed. + + @param parent + Parent window, must be non-@NULL. + + @param id + The identifier for the control. + + @param anim + The initial animation shown in the control. + + @param pos + Initial position. + + @param size + Initial size. + + @param style + The window style, see wxAC_* flags. + + @param name + Control name. + + @returns @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow * parent, wxWindowID id, + const wxAnimation& anim, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxAC_DEFAULT_STYLE, + const wxString& name = "animationctrl"); + + /** + Returns the animation associated with this control. + */ + wxAnimation GetAnimation(); + + /** + Returns the inactive bitmap shown in this control when the; + see SetInactiveBitmap() for more info. + */ + wxBitmap GetInactiveBitmap(); + + /** + Returns @true if the animation is being played. + */ + bool IsPlaying(); + + /** + Loads the animation from the given file and calls SetAnimation(). + See wxAnimation::LoadFile for more info. + */ + bool LoadFile(const wxString & file, + wxAnimationType animType = wxANIMATION_TYPE_ANY); + + /** + Starts playing the animation. + The animation is always played in loop mode (unless the last frame of the + animation + has an infinite delay time) and always start from the first frame + (even if you @ref stop() stopped it while some other frame was + displayed). + */ + bool Play(); + + /** + Sets the animation to play in this control. + If the previous animation is being played, it's @ref stop() Stopped. + + Until Play() isn't called, a static image, the first + frame of the given animation or the background colour will be shown + (see SetInactiveBitmap() for more info). + */ + void SetAnimation(const wxAnimation & anim); + + /** + Sets the bitmap to show on the control when it's not playing an animation. + If you set as inactive bitmap @c wxNullBitmap (which is the default), then the + first frame of the animation is instead shown when the control is inactive; in + this case, + if there's no valid animation associated with the control (see + wxAnimationCtrl::SetAnimation), + then the background colour of the window is shown. + + If the control is not playing the animation, the given bitmap will be + immediately + shown, otherwise it will be shown as soon as Stop() + is called. + + Note that the inactive bitmap, if smaller than the control's size, will be + centered in + the control; if bigger, it will be stretched to fit it. + */ + void SetInactiveBitmap(const wxBitmap& bmp); + + /** + Stops playing the animation. + The control will show the first frame of the animation, a custom static image or + the window's background colour as specified by the + last SetInactiveBitmap() call. + */ + void Stop(); +}; + + +/** + @class wxAnimation + @wxheader{animate.h} + + This class encapsulates the concept of a platform-dependent animation. + An animation is a sequence of frames of the same size. + Sound is not supported by wxAnimation. + + @library{wxadv} + @category{FIXME} + + @stdobjects + Objects: + wxNullAnimation + + @seealso + wxAnimationCtrl +*/ +class wxAnimation : public wxGDIObject +{ +public: + //@{ + /** + Loads an animation from a file. + + @param name + The name of the file to load. + + @param type + See LoadFile for more info. + */ + wxAnimation(); + wxAnimation(const wxAnimation& anim); + wxAnimation(const wxString& name, + wxAnimationType type = wxANIMATION_TYPE_ANY); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxAnimation(); + + /** + Returns the delay for the i-th frame in milliseconds. + If @c -1 is returned the frame is to be displayed forever. + */ + int GetDelay(unsigned int i); + + /** + Returns the i-th frame as a wxImage. + */ + wxImage GetFrame(unsigned int i); + + /** + Returns the number of frames for this animation. + */ + unsigned int GetFrameCount(); + + /** + Returns the size of the animation. + */ + wxSize GetSize(); + + /** + Returns @true if animation data is present. + */ +#define bool IsOk() /* implementation is private */ + + /** + Loads an animation from the given stream. + + @param stream + The stream to use to load the animation. + + @param type + One of the following values: + + + wxANIMATION_TYPE_GIF + + + Load an animated GIF file. + + wxANIMATION_TYPE_ANI + + + Load an ANI file. + + wxANIMATION_TYPE_ANY + + + Try to autodetect the filetype. + + @returns @true if the operation succeeded, @false otherwise. + */ + bool Load(wxInputStream& stream, + wxAnimationType type = wxANIMATION_TYPE_ANY); + + /** + Loads an animation from a file. + + @param name + A filename. + + @param type + One of the following values: + + + wxANIMATION_TYPE_GIF + + + Load an animated GIF file. + + wxANIMATION_TYPE_ANI + + + Load an ANI file. + + wxANIMATION_TYPE_ANY + + + Try to autodetect the filetype. + + @returns @true if the operation succeeded, @false otherwise. + */ + bool LoadFile(const wxString& name, + wxAnimationType type = wxANIMATION_TYPE_ANY); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxAnimation operator =(const wxAnimation& brush); +}; diff --git a/interface/app.h b/interface/app.h new file mode 100644 index 0000000000..1167de2282 --- /dev/null +++ b/interface/app.h @@ -0,0 +1,937 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: app.h +// Purpose: documentation for wxApp class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxApp + @wxheader{app.h} + + The @b wxApp class represents the application itself. It is used + to: + + set and get application-wide properties; + implement the windowing system message or event loop; + initiate application processing via wxApp::OnInit; + allow default processing of events not handled by other + objects in the application. + + You should use the macro IMPLEMENT_APP(appClass) in your application + implementation + file to tell wxWidgets how to create an instance of your application class. + + Use DECLARE_APP(appClass) in a header file if you want the wxGetApp function + (which returns + a reference to your application object) to be visible to other files. + + @library{wxbase} + @category{appmanagement} + + @seealso + @ref overview_wxappoverview "wxApp overview" +*/ +class wxApp : public wxEvtHandler +{ +public: + /** + Constructor. Called implicitly with a definition of a wxApp object. + */ + wxApp(); + + /** + Destructor. Will be called implicitly on program exit if the wxApp + object is created on the stack. + */ + ~wxApp(); + + /** + Creates a wxLog class for the application to use for logging errors. The default + implementation returns a new wxLogGui class. + + @sa wxLog + */ + virtual wxLog* CreateLogTarget(); + + /** + Creates the wxAppTraits object when GetTraits() + needs it for the first time. + + @sa wxAppTraits + */ + virtual wxAppTraits * CreateTraits(); + + /** + Dispatches the next event in the windowing system event queue. + + This can be used for programming event loops, e.g. + + @sa Pending() + */ + virtual void Dispatch(); + + /** + Call this to explicitly exit the main message (event) loop. + You should normally exit the main loop (and the application) by deleting + the top window. + */ + virtual void ExitMainLoop(); + + /** + This function is called before processing any event and allows the application + to preempt the processing of some events. If this method returns -1 the event + is processed normally, otherwise either @true or @false should be + returned and the event processing stops immediately considering that the event + had been already processed (for the former return value) or that it is not + going to be processed at all (for the latter one). + */ + int FilterEvent(wxEvent& event); + + /** + Returns the user-readable application name. The difference between this string + and the one returned by GetAppName() is that this one + is meant to be shown to the user and so should be used for the window titles, + page headers and so on while the other one should be only used internally, e.g. + for the file names or configuration file keys. + + By default, returns the same string as GetAppName(). + + This function is new since wxWidgets version 2.9.0 + */ + wxString GetAppDisplayName(); + + /** + Returns the application name. + + @remarks wxWidgets sets this to a reasonable default before calling + OnInit(), but the application can reset it at + will. + + @sa GetAppDisplayName() + */ + wxString GetAppName(); + + /** + Gets the class name of the application. The class name may be used in a + platform specific + manner to refer to the application. + + @sa SetClassName() + */ + wxString GetClassName(); + + /** + Returns @true if the application will exit when the top-level window is deleted, + @false + otherwise. + + @sa SetExitOnFrameDelete(), @ref overview_wxappshutdownoverview "wxApp + shutdown overview" + */ + bool GetExitOnFrameDelete(); + + /** + Returns the one and only global application object. + Usually @c wxTheApp is usead instead. + + @sa SetInstance() + */ + static wxAppConsole * GetInstance(); + + /** + Returns a pointer to the top window. + + @remarks If the top window hasn't been set using SetTopWindow(), + this function will find the first top-level window + (frame or dialog) and return that. + + @sa SetTopWindow() + */ + virtual wxWindow * GetTopWindow(); + + /** + Returns a pointer to the wxAppTraits object for the application. + If you want to customize the wxAppTraits object, you must override the + CreateTraits() function. + */ + wxAppTraits * GetTraits(); + + /** + Returns @true if the application will use the best visual on systems that support + different visuals, @false otherwise. + + @sa SetUseBestVisual() + */ + bool GetUseBestVisual(); + + /** + Returns the user-readable vendor name. The difference between this string + and the one returned by GetVendorName() is that this one + is meant to be shown to the user and so should be used for the window titles, + page headers and so on while the other one should be only used internally, e.g. + for the file names or configuration file keys. + + By default, returns the same string as GetVendorName(). + + This function is new since wxWidgets version 2.9.0 + */ + wxString GetVendorDisplayName(); + + /** + Returns the application's vendor name. + */ + wxString GetVendorName(); + + /** + This function simply invokes the given method @e func of the specified + event handler @e handler with the @e event as parameter. It exists solely + to allow to catch the C++ exceptions which could be thrown by all event + handlers in the application in one place: if you want to do this, override this + function in your wxApp-derived class and add try/catch clause(s) to it. + */ + virtual void HandleEvent(wxEvtHandler handler, + wxEventFunction func, + wxEvent& event); + + /** + 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. + */ + bool IsActive(); + + /** + Returns @true if the main event loop is currently running, i.e. if the + application is inside OnRun(). + + This can be useful to test whether events can be dispatched. For example, + if this function returns @false, non-blocking sockets cannot be used because + the events from them would never be processed. + */ + static bool IsMainLoopRunning(); + + /** + Mac specific. Called in response of an "open-application" Apple event. + Override this to create a new document in your app. + */ + void MacNewFile(); + + /** + Mac specific. Called in response of an "open-document" Apple event. You need to + override this method in order to open a document file after the + user double clicked on it or if the document file was dropped + on either the running application or the application icon in + Finder. + */ + void MacOpenFile(const wxString& fileName); + + /** + Mac specific. Called in response of a "get-url" Apple event. + */ + void MacOpenURL(const wxString& url); + + /** + Mac specific. Called in response of a "print-document" Apple event. + */ + void MacPrintFile(const wxString& fileName); + + /** + Mac specific. Called in response of a "reopen-application" Apple event. + */ + void MacReopenApp(); + + /** + Called by wxWidgets on creation of the application. Override this if you wish + to provide your own (environment-dependent) main loop. + + @returns Returns 0 under X, and the wParam of the WM_QUIT message under + Windows. + */ + virtual int MainLoop(); + + /** + This function is called when an assert failure occurs, i.e. the condition + specified in wxASSERT macro evaluated to @false. + It is only called in debug mode (when @c __WXDEBUG__ is defined) as + asserts are not left in the release code at all. + + The base class version shows the default assert failure dialog box proposing to + the user to stop the program, continue or ignore all subsequent asserts. + + @param file + the name of the source file where the assert occurred + + @param line + the line number in this file where the assert occurred + + @param func + the name of the function where the assert occurred, may be + empty if the compiler doesn't support C99 __FUNCTION__ + + @param cond + the condition of the failed assert in text form + + @param msg + the message specified as argument to + wxASSERT_MSG or wxFAIL_MSG, will + be @NULL if just wxASSERT or wxFAIL + was used + */ + void OnAssertFailure(const wxChar file, int line, + const wxChar func, + const wxChar cond, + const wxChar msg); + + /** + Called when command line parsing fails (i.e. an incorrect command line option + was specified by the user). The default behaviour is to show the program usage + text and abort the program. + + Return @true to continue normal execution or @false to return + @false from OnInit() thus terminating the program. + + @sa OnInitCmdLine() + */ + bool OnCmdLineError(wxCmdLineParser& parser); + + /** + Called when the help option (@c --help) was specified on the command line. + The default behaviour is to show the program usage text and abort the program. + + Return @true to continue normal execution or @false to return + @false from OnInit() thus terminating the program. + + @sa OnInitCmdLine() + */ + bool OnCmdLineHelp(wxCmdLineParser& parser); + + /** + Called after the command line had been successfully parsed. You may override + this method to test for the values of the various parameters which could be + set from the command line. + + Don't forget to call the base class version unless you want to suppress + processing of the standard command line options. + + Return @true to continue normal execution or @false to return + @false from OnInit() thus terminating the program. + + @sa OnInitCmdLine() + */ + bool OnCmdLineParsed(wxCmdLineParser& parser); + + /** + This function is called if an unhandled exception occurs inside the main + application event loop. It can return @true to ignore the exception and to + continue running the loop or @false to exit the loop and terminate the + program. In the latter case it can also use C++ @c throw keyword to + rethrow the current exception. + + The default behaviour of this function is the latter in all ports except under + Windows where a dialog is shown to the user which allows him to choose between + the different options. You may override this function in your class to do + something more appropriate. + + Finally note that if the exception is rethrown from here, it can be caught in + OnUnhandledException(). + */ + virtual bool OnExceptionInMainLoop(); + + /** + Override this member function for any processing which needs to be + done as the application is about to exit. OnExit is called after + destroying all application windows and controls, but before + wxWidgets cleanup. Note that it is not called at all if + OnInit() failed. + + The return value of this function is currently ignored, return the same value + as returned by the base class method if you override it. + */ + virtual int OnExit(); + + /** + This function may be called if something fatal happens: an unhandled + exception under Win32 or a a fatal signal under Unix, for example. However, + this will not happen by default: you have to explicitly call + wxHandleFatalExceptions to enable this. + + Generally speaking, this function should only show a message to the user and + return. You may attempt to save unsaved data but this is not guaranteed to + work and, in fact, probably won't. + + @sa wxHandleFatalExceptions + */ + void OnFatalException(); + + /** + This must be provided by the application, and will usually create the + application's main window, optionally calling + SetTopWindow(). You may use + OnExit() to clean up anything initialized here, provided + that the function returns @true. + + Notice that if you want to to use the command line processing provided by + wxWidgets you have to call the base class version in the derived class + OnInit(). + + Return @true to continue processing, @false to exit the application + immediately. + */ + bool OnInit(); + + /** + Called from OnInit() and may be used to initialize the + parser with the command line options for this application. The base class + versions adds support for a few standard options only. + */ + void OnInitCmdLine(wxCmdLineParser& parser); + + /** + This virtual function is where the execution of a program written in wxWidgets + starts. The default implementation just enters the main loop and starts + handling the events until it terminates, either because + ExitMainLoop() has been explicitly called or because + the last frame has been deleted and + GetExitOnFrameDelete() flag is @true (this + is the default). + + The return value of this function becomes the exit code of the program, so it + should return 0 in case of successful termination. + */ + virtual int OnRun(); + + /** + This function is called when an unhandled C++ exception occurs inside + OnRun() (the exceptions which occur during the program + startup and shutdown might not be caught at all). Notice that by now the main + event loop has been terminated and the program will exit, if you want to + prevent this from happening (i.e. continue running after catching an exception) + you need to override OnExceptionInMainLoop(). + + The default implementation shows information about the exception in debug build + but does nothing in the release build. + */ + virtual void OnUnhandledException(); + + /** + Returns @true if unprocessed events are in the window system event queue. + + @sa Dispatch() + */ + virtual bool Pending(); + + /** + 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: + */ + bool ProcessMessage(WXMSG * msg); + + /** + Sends idle events to a window and its children. + + Please note that this function is internal to wxWidgets and shouldn't be used + by user code. + + @remarks These functions poll the top-level windows, and their children, + for idle event processing. If @true is returned, more + OnIdle processing is requested by one or more window. + + @sa wxIdleEvent + */ + bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); + + /** + Set the application name to be used in the user-visible places such as window + titles. See GetAppDisplayName() for more about + the differences between the display name and name. + */ + void SetAppDisplayName(const wxString& name); + + /** + Sets the name of the application. This name should be used for file names, + configuration file entries and other internal strings. For the user-visible + strings, such as the window titles, the application display name set by + SetAppDisplayName() is used instead. + + By default the application name is set to the name of its executable file. + + @sa GetAppName() + */ + void SetAppName(const wxString& name); + + /** + Sets the class name of the application. This may be used in a platform specific + manner to refer to the application. + + @sa GetClassName() + */ + void SetClassName(const wxString& name); + + /** + Allows the programmer to specify whether the application will exit when the + top-level frame is deleted. + + @param flag + If @true (the default), the application will exit when the top-level frame is + deleted. If @false, the application will continue to run. + + @sa GetExitOnFrameDelete(), @ref overview_wxappshutdownoverview "wxApp + shutdown overview" + */ + void SetExitOnFrameDelete(bool flag); + + /** + Allows external code to modify global @c wxTheApp, but you should really + know what you're doing if you call it. + + @param app + Replacement for the global application object. + + @sa GetInstance() + */ + static void SetInstance(wxAppConsole* app); + + /** + Allows runtime switching of the UI environment theme. Currently implemented for + wxGTK2-only. + + Return @true if theme was successfully changed. + + @param theme + The name of the new theme or an absolute path to a gtkrc-theme-file + */ + bool SetNativeTheme(); + + /** + Sets the 'top' window. You can call this from within OnInit() to + let wxWidgets know which is the main window. You don't have to set the top + window; + it is only a convenience so that (for example) certain dialogs without parents + can use a + specific window as the top window. If no top window is specified by the + application, + wxWidgets just uses the first frame or dialog in its top-level window list, + when it + needs to use the top window. + + @param window + The new top window. + + @sa GetTopWindow(), OnInit() + */ + void SetTopWindow(wxWindow* window); + + /** + Allows the programmer to specify whether the application will use the best + visual + on systems that support several visual on the same display. This is typically + the + case under Solaris and IRIX, where the default visual is only 8-bit whereas + certain + applications are supposed to run in TrueColour mode. + + If @e forceTrueColour is @true then the application will try to force + using a TrueColour visual and abort the app if none is found. + + Note that this function has to be called in the constructor of the @c wxApp + instance and won't have any effect when called later on. + + This function currently only has effect under GTK. + + @param flag + If @true, the app will use the best visual. + */ + void SetUseBestVisual(bool flag, bool forceTrueColour = @false); + + /** + Set the vendor name to be used in the user-visible places. See + GetVendorDisplayName() for more about + the differences between the display name and name. + */ + void SetVendorDisplayName(const wxString& name); + + /** + Sets the name of application's vendor. The name will be used + in registry access. A default name is set by + wxWidgets. + + @sa GetVendorName() + */ + void SetVendorName(const wxString& name); + + /** + Yields control to pending messages in the windowing system. This can be useful, + for example, when a + time-consuming process writes to a text window. Without an occasional + yield, the text window will not be updated properly, and on systems with + cooperative multitasking, such as Windows 3.1 other processes will not respond. + + Caution should be exercised, however, since yielding may allow the + user to perform actions which are not compatible with the current task. + Disabling menu items or whole menus during processing can avoid unwanted + reentrance of code: see ::wxSafeYield for a better + function. + + Note that Yield() will not flush the message logs. This is intentional as + calling Yield() is usually done to quickly update the screen and popping up a + message box dialog may be undesirable. If you do wish to flush the log + messages immediately (otherwise it will be done during the next idle loop + iteration), call wxLog::FlushActive. + + Calling Yield() recursively is normally an error and an assert failure is + raised in debug build if such situation is detected. However if the + @e onlyIfNeeded parameter is @true, the method will just silently + return @false instead. + */ + bool Yield(bool onlyIfNeeded = @false); + + /** + int argc + + Number of command line arguments (after environment-specific processing). + */ + + + /** + wxChar ** argv + + Command line arguments (after environment-specific processing). + Under Windows and Linux/Unix, you should parse the command line + arguments and check for files to be opened when starting your + application. Under OS X, you need to override MacOpenFile() + since command line arguments are used differently there. + + You may use the wxCmdLineParser to + parse command line arguments. + */ +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +//@{ +/** + For all normal, informational messages. They also appear in a message box by + default (but it can be changed). +*/ +void wxLogMessage(const char * formatString, ... ); + void wxVLogMessage(const char * formatString, va_list argPtr); +//@} + +//@{ +/** + For verbose output. Normally, it is suppressed, but + might be activated if the user wishes to know more details about the program + progress (another, but possibly confusing name for the same function is @b + wxLogInfo). +*/ +void wxLogVerbose(const char * formatString, ... ); + void wxVLogVerbose(const char * formatString, va_list argPtr); +//@} + +/** + This is used in headers to create a forward declaration of the + wxGetApp function implemented by + wxIMPLEMENT_APP. It creates the declaration + @c className wxGetApp(void). + + Example: + @code + wxDECLARE_APP(MyApp) + @endcode +*/ +#define wxDECLARE_APP() /* implementation is private */ + +/** + Exits application after calling wxApp::OnExit. + Should only be used in an emergency: normally the top-level frame + should be deleted (after deleting all other frames) to terminate the + application. See wxCloseEvent and wxApp. +*/ +void wxExit(); + +//@{ +/** + For warnings - they are also normally shown to the user, but don't interrupt + the program work. +*/ +void wxLogWarning(const char * formatString, ... ); + void wxVLogWarning(const char * formatString, va_list argPtr); +//@} + +//@{ +/** + Like wxLogError, but also + terminates the program with the exit code 3. Using @e abort() standard + function also terminates the program with this exit code. +*/ +void wxLogFatalError(const char * formatString, ... ); + void wxVLogFatalError(const char * formatString, + va_list argPtr); +//@} + +/** + If @e doIt is @true, the fatal exceptions (also known as general protection + faults under Windows or segmentation violations in the Unix world) will be + caught and passed to wxApp::OnFatalException. + By default, i.e. before this function is called, they will be handled in the + normal way which usually just means that the application will be terminated. + Calling wxHandleFatalExceptions() with @e doIt equal to @false will restore + this default behaviour. + + Notice that this function is only available if + @c wxUSE_ON_FATAL_EXCEPTION is 1 and under Windows platform this + requires a compiler with support for SEH (structured exception handling) which + currently means only Microsoft Visual C++ or a recent Borland C++ version. +*/ +bool wxHandleFatalExceptions(bool doIt = @true); + +/** + This is used in the application class implementation file to make the + application class known to + wxWidgets for dynamic construction. You use this instead of + + Old form: + @code + MyApp myApp; + @endcode + + New form: + @code + IMPLEMENT_APP(MyApp) + @endcode + + See also DECLARE_APP. +*/ +#define IMPLEMENT_APP() /* implementation is private */ + +/** + Returns the error code from the last system call. This function uses + @c errno on Unix platforms and @c GetLastError under Win32. + + @sa wxSysErrorMsg, wxLogSysError +*/ +unsigned long wxSysErrorCode(); + +/** + In a GUI application, this function posts @e event to the specified @e dest + object using wxEvtHandler::AddPendingEvent. + Otherwise, it dispatches @e event immediately using + wxEvtHandler::ProcessEvent. + See the respective documentation for details (and caveats). +*/ +void wxPostEvent(wxEvtHandler * dest, wxEvent& event); + +//@{ +/** + The functions to use for error messages, i.e. the messages that must be shown + to the user. The default processing is to pop up a message box to inform the + user about it. +*/ +void wxLogError(const char * formatString, ... ); + void wxVLogError(const char * formatString, va_list argPtr); +//@} + +//@{ +/** + As @b wxLogDebug, trace functions only do something in debug build and + expand to nothing in the release one. The reason for making + it a separate function from it is that usually there are a lot of trace + messages, so it might make sense to separate them from other debug messages. + + The trace messages also usually can be separated into different categories and + the second and third versions of this function only log the message if the + @e mask which it has is currently enabled in wxLog. This + allows to selectively trace only some operations and not others by changing + the value of the trace mask (possible during the run-time). + + For the second function (taking a string mask), the message is logged only if + the mask has been previously enabled by the call to + wxLog::AddTraceMask or by setting + @ref overview_envvars "@c WXTRACE environment variable". + The predefined string trace masks + used by wxWidgets are: + + wxTRACE_MemAlloc: trace memory allocation (new/delete) + wxTRACE_Messages: trace window messages/X callbacks + wxTRACE_ResAlloc: trace GDI resource allocation + wxTRACE_RefCount: trace various ref counting operations + wxTRACE_OleCalls: trace OLE method calls (Win32 only) + + @b Caveats: since both the mask and the format string are strings, + this might lead to function signature confusion in some cases: + if you intend to call the format string only version of wxLogTrace, + then add a %s format string parameter and then supply a second string parameter + for that %s, the string mask version of wxLogTrace will erroneously get called instead, since you are supplying two string parameters to the function. + In this case you'll unfortunately have to avoid having two leading + string parameters, e.g. by adding a bogus integer (with its %d format string). + + The third version of the function only logs the message if all the bits + corresponding to the @e mask are set in the wxLog trace mask which can be + set by wxLog::SetTraceMask. This version is less + flexible than the previous one because it doesn't allow defining the user + trace masks easily - this is why it is deprecated in favour of using string + trace masks. + + wxTraceMemAlloc: trace memory allocation (new/delete) + wxTraceMessages: trace window messages/X callbacks + wxTraceResAlloc: trace GDI resource allocation + wxTraceRefCount: trace various ref counting operations + wxTraceOleCalls: trace OLE method calls (Win32 only) +*/ +void wxLogTrace(const char * formatString, ... ); + void wxVLogTrace(const char * formatString, va_list argPtr); + void wxLogTrace(const char * mask, const char * formatString, + ... ); + void wxVLogTrace(const char * mask, + const char * formatString, + va_list argPtr); + void wxLogTrace(wxTraceMask mask, const char * formatString, + ... ); + void wxVLogTrace(wxTraceMask mask, const char * formatString, + va_list argPtr); +//@} + +/** + Returns the error message corresponding to the given system error code. If + @e errCode is 0 (default), the last error code (as returned by + wxSysErrorCode) is used. + + @sa wxSysErrorCode, wxLogSysError +*/ +const wxChar * wxSysErrorMsg(unsigned long errCode = 0); + +/** + This function is for use in console (wxBase) programs only. It must be called + once for each previous successful call to wxInitialize. +*/ +void wxUninitialize(); + +//@{ +/** + The right functions for debug output. They only do something in debug + mode (when the preprocessor symbol __WXDEBUG__ is defined) and expand to + nothing in release mode (otherwise). +*/ +void wxLogDebug(const char * formatString, ... ); + void wxVLogDebug(const char * formatString, va_list argPtr); +//@} + +/** + This function doesn't exist in wxWidgets but it is created by using + the IMPLEMENT_APP macro. Thus, before using it + anywhere but in the same module where this macro is used, you must make it + available using DECLARE_APP. + + The advantage of using this function compared to directly using the global + wxTheApp pointer is that the latter is of type @c wxApp * and so wouldn't + allow you to access the functions specific to your application class but not + present in wxApp while wxGetApp() returns the object of the right type. +*/ +wxAppDerivedClass wxGetApp(); + +//@{ +/** + Messages logged by these functions will appear in the statusbar of the @e frame + or of the top level application window by default (i.e. when using + the second version of the functions). + + If the target frame doesn't have a statusbar, the message will be lost. +*/ +void wxLogStatus(wxFrame * frame, const char * formatString, + ... ); + void wxVLogStatus(wxFrame * frame, const char * formatString, + va_list argPtr); + void wxLogStatus(const char * formatString, ... ); + void wxVLogStatus(const char * formatString, va_list argPtr); +//@} + +/** + This function is used in wxBase only and only if you don't create + wxApp object at all. In this case you must call it from your + @c main() function before calling any other wxWidgets functions. + + If the function returns @false the initialization could not be performed, + in this case the library cannot be used and + wxUninitialize shouldn't be called neither. + + This function may be called several times but + wxUninitialize must be called for each successful + call to this function. +*/ +bool wxInitialize(); + +/** + This is used in headers to create a forward declaration of the + wxGetApp function implemented by + IMPLEMENT_APP. It creates the declaration + @c className wxGetApp(void). + + Example: + @code + DECLARE_APP(MyApp) + @endcode +*/ +#define DECLARE_APP() /* implementation is private */ + +/** + Calls wxApp::Yield. + + This function is kept only for backwards compatibility. Please use + the wxApp::Yield method instead in any new code. +*/ +bool wxYield(); + +//@{ +/** + Mostly used by wxWidgets itself, but might be handy for logging errors after + system call (API function) failure. It logs the specified message text as well + as the last system error code (@e errno or @e ::GetLastError() depending + on the platform) and the corresponding error message. The second form + of this function takes the error code explicitly as the first argument. + + @sa wxSysErrorCode, wxSysErrorMsg +*/ +void wxLogSysError(const char * formatString, ... ); + void wxVLogSysError(const char * formatString, + va_list argPtr); +//@} + +//@{ +/** + This initializes wxWidgets in a platform-dependent way. Use this if you are not + using the default wxWidgets entry code (e.g. main or WinMain). For example, you + can initialize wxWidgets from an Microsoft Foundation Classes application using + this function. + + The following overload of wxEntry is available under all platforms: + + (notice that under Windows CE platform, and only there, the type of + @e pCmdLine is @c wchar_t *, otherwise it is @c char *, even in + Unicode build). + + @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static + function wxApp::CleanUp. For example, if exiting from + an MFC application that also uses wxWidgets: + + @sa wxEntryStart +*/ +int wxEntry(int& argc, wxChar ** argv); + int wxEntry(HINSTANCE hInstance, + HINSTANCE hPrevInstance = @NULL, + char * pCmdLine = @NULL, + int nCmdShow = SW_SHOWNORMAL); +//@} + diff --git a/interface/apptrait.h b/interface/apptrait.h new file mode 100644 index 0000000000..c8d28a51d7 --- /dev/null +++ b/interface/apptrait.h @@ -0,0 +1,120 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: apptrait.h +// Purpose: documentation for wxAppTraits class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAppTraits + @wxheader{apptrait.h} + + The @b wxAppTraits class defines various configurable aspects of a wxApp. + You can access it using wxApp::GetTraits function and you can + create your own wxAppTraits overriding the + wxApp::CreateTraits function. + + By default, wxWidgets creates a @c wxConsoleAppTraits object for console + applications + (i.e. those applications linked against wxBase library only - see the + @ref overview_librarieslist "Libraries list" page) and a @c wxGUIAppTraits + object for GUI + applications. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxappoverview "wxApp overview", wxApp +*/ +class wxAppTraits +{ +public: + /** + Called by wxWidgets to create the default configuration object for the + application. The default version creates a registry-based + wxRegConfig class under MSW and + wxFileConfig under all other platforms. The + wxApp wxApp::GetAppName and + wxApp::GetVendorName methods are used to determine the + registry key or file name. + */ + virtual wxConfigBase * CreateConfig(); + + /** + Creates the global font mapper object used for encodings/charset mapping. + */ + virtual wxFontMapper * CreateFontMapper(); + + /** + Creates the default log target for the application. + */ + virtual wxLog * CreateLogTarget(); + + /** + Creates the global object used for printing out messages. + */ + virtual wxMessageOutput * CreateMessageOutput(); + + /** + Returns the renderer to use for drawing the generic controls (return value may + be @NULL + in which case the default renderer for the current platform is used); + this is used in GUI mode only and always returns @NULL in console. + + NOTE: returned pointer will be deleted by the caller. + */ + virtual wxRendererNative * CreateRenderer(); + + /** + This method returns the name of the desktop environment currently + running in a Unix desktop. Currently only "KDE" or "GNOME" are + supported and the code uses the X11 session protocol vendor name + to figure out, which desktop environment is running. The method + returns an empty string otherwise and on all other platforms. + */ + virtual wxString GetDesktopEnvironment(); + + /** + Returns the wxStandardPaths object for the application. + It's normally the same for wxBase and wxGUI except in the case of wxMac and + wxCocoa. + */ + virtual wxStandardPaths GetStandardPaths(); + + /** + Returns the wxWidgets port ID used by the running program and eventually + fills the given pointers with the values of the major and minor digits + of the native toolkit currently used. + The version numbers returned are thus detected at run-time and not compile-time + (except when this is not possible e.g. wxMotif). + + E.g. if your program is using wxGTK port this function will return wxPORT_GTK + and + put in given pointers the versions of the GTK library in use. + + See wxPlatformInfo for more details. + */ + virtual wxPortId GetToolkitVersion(int * major = @NULL, + int * minor = @NULL); + + /** + Returns @true if @c fprintf(stderr) goes somewhere, @false otherwise. + */ + virtual bool HasStderr(); + + /** + Returns @true if the library was built as wxUniversal. Always returns + @false for wxBase-only apps. + */ + bool IsUsingUniversalWidgets(); + + /** + Shows the assert dialog with the specified message in GUI mode or just prints + the string to stderr in console mode. + + Returns @true to suppress subsequent asserts, @false to continue as before. + */ + virtual bool ShowAssertDialog(const wxString & msg); +}; diff --git a/interface/archive.h b/interface/archive.h new file mode 100644 index 0000000000..18a6754df7 --- /dev/null +++ b/interface/archive.h @@ -0,0 +1,589 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: archive.h +// Purpose: documentation for wxArchiveInputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxArchiveInputStream + @wxheader{archive.h} + + An abstract base class which serves as a common interface to + archive input streams such as wxZipInputStream. + + wxArchiveInputStream::GetNextEntry returns an + wxArchiveEntry object containing the meta-data + for the next entry in the archive (and gives away ownership). Reading from + the wxArchiveInputStream then returns the entry's data. Eof() becomes @true + after an attempt has been made to read past the end of the entry's data. + When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarc "Archive formats such as zip", wxArchiveEntry, + wxArchiveOutputStream +*/ +class wxArchiveInputStream : public wxFilterInputStream +{ +public: + /** + Closes the current entry. On a non-seekable stream reads to the end of + the current entry first. + */ + bool CloseEntry(); + + /** + Closes the current entry if one is open, then reads the meta-data for + the next entry and returns it in a wxArchiveEntry + object, giving away ownership. Reading this wxArchiveInputStream then + returns the entry's data. + */ + wxArchiveEntry* GetNextEntry(); + + /** + Closes the current entry if one is open, then opens the entry specified + by the wxArchiveEntry object. + + @e entry must be from the same archive file that this + wxArchiveInputStream is reading, and it must be reading it from a + seekable stream. + */ + bool OpenEntry(wxArchiveEntry& entry); +}; + + +/** + @class wxArchiveOutputStream + @wxheader{archive.h} + + An abstract base class which serves as a common interface to + archive output streams such as wxZipOutputStream. + + wxArchiveOutputStream::PutNextEntry is used + to create a new entry in the output archive, then the entry's data is + written to the wxArchiveOutputStream. Another call to PutNextEntry() + closes the current entry and begins the next. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarc "Archive formats such as zip", wxArchiveEntry, + wxArchiveInputStream +*/ +class wxArchiveOutputStream : public wxFilterOutputStream +{ +public: + /** + Calls Close() if it has not already + been called. + */ + ~wxArchiveOutputStream(); + + /** + Closes the archive, returning @true if it was successfully written. + Called by the destructor if not called explicitly. + */ + bool Close(); + + /** + Close the current entry. It is called implicitly whenever another new + entry is created with CopyEntry() + or PutNextEntry(), or + when the archive is closed. + */ + bool CloseEntry(); + + /** + 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. + */ + bool CopyArchiveMetaData(wxArchiveInputStream& stream); + + /** + Takes ownership of @e entry and uses it to create a new entry in the + archive. @e entry is then opened in the input stream @e 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. + + @e entry must be from the same archive file that @e stream is + accessing. For non-seekable streams, @e entry must also be the last + thing read from @e stream. + */ + bool CopyEntry(wxArchiveEntry* entry, + wxArchiveInputStream& 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. + */ + bool PutNextDirEntry(const wxString& name); + + //@{ + /** + , @b off_t@e size = wxInvalidOffset) + + Create a new entry with the given name, timestamp and size. The entry's + data can then be written by writing to this wxArchiveOutputStream. + */ + bool PutNextEntry(wxArchiveEntry* entry); + bool PutNextEntry(const wxString& name); + //@} +}; + + +/** + @class wxArchiveEntry + @wxheader{archive.h} + + 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. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarc "Archive formats such as zip", @ref overview_wxarcgeneric + "Generic archive programming", wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier +*/ +class wxArchiveEntry : public wxObject +{ +public: + /** + Returns a copy of this entry object. + */ + wxArchiveEntry* Clone(); + + //@{ + /** + The entry's timestamp. + */ + wxDateTime GetDateTime(); + void SetDateTime(const wxDateTime& dt); + //@} + + //@{ + /** + 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(). + */ + wxString GetName(wxPathFormat format = wxPATH_NATIVE); + void SetName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE); + //@} + + //@{ + /** + The size of the entry's data in bytes. + */ + off_t GetSize(); + void SetSize(off_t size); + //@} + + /** + Returns the path format used internally within the archive to store + filenames. + */ + wxPathFormat GetInternalFormat(); + + /** + 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. + + @sa @ref overview_wxarcbyname "Looking up an archive entry by name" + */ + wxString GetInternalName(); + + /** + Returns a numeric value unique to the entry within the archive. + */ + off_t GetOffset(); + + //@{ + /** + 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. + */ + bool IsDir(); + void SetIsDir(bool isDir = @true); + //@} + + //@{ + /** + True if the entry is a read-only file. + */ + bool IsReadOnly(); + void SetIsReadOnly(bool isReadOnly = @true); + //@} + + //@{ + /** + Sets the notifier for this entry. + Whenever the wxArchiveInputStream updates + this entry, it will then invoke the associated + notifier's wxArchiveNotifier::OnEntryUpdated + method. + + Setting a notifier is not usually necessary. It is used to handle + certain cases when modifying an archive in a pipeline (i.e. between + non-seekable streams). + */ + void SetNotifier(wxArchiveNotifier& notifier); + void UnsetNotifier(); + //@} +}; + + +/** + @class wxArchiveClassFactory + @wxheader{archive.h} + + Allows the creation of streams to handle archive formats such + as zip and tar. + + For example, given a filename you can search for a factory that will + handle it and create a stream to read it: + + @code + factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT); + if (factory) + stream = factory-NewStream(new wxFFileInputStream(filename)); + @endcode + + wxArchiveClassFactory::Find can also search + for a factory by MIME type or wxFileSystem protocol. + The available factories can be enumerated + using @ref wxArchiveClassFactory::getfirst "GetFirst() and GetNext". + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarc "Archive formats such as zip", @ref overview_wxarcgeneric + "Generic archive programming", wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory +*/ +class wxArchiveClassFactory : public wxObject +{ +public: + /** + Returns @true if this factory can handle the given protocol, MIME type + or file extension. + + When using wxSTREAM_FILEEXT for the second parameter, the first parameter + can be a complete filename rather than just an extension. + */ + bool CanHandle(const wxChar* protocol, + wxStreamProtocolType type = wxSTREAM_PROTOCOL); + + /** + A static member that finds a factory that can handle a given protocol, MIME + type or file extension. Returns a pointer to the class factory if found, or + @NULL otherwise. It does not give away ownership of the factory. + + When using wxSTREAM_FILEEXT for the second parameter, the first parameter + can be a complete filename rather than just an extension. + */ + static const wxArchiveClassFactory* Find(const wxChar* protocol, + wxStreamProtocolType type = wxSTREAM_PROTOCOL); + + //@{ + /** + The wxMBConv object that the created streams + will use when translating meta-data. The initial default, set by the + constructor, is wxConvLocal. + */ + wxMBConv GetConv(); + void SetConv(wxMBConv& conv); + //@} + + //@{ + /** + GetFirst and GetNext can be used to enumerate the available factories. + + For example, to list them: + GetFirst()/GetNext() return a pointer to a factory or @NULL if no more + are available. They do not give away ownership of the factory. + */ + static const wxArchiveClassFactory* GetFirst(); + const wxArchiveClassFactory* GetNext(); + //@} + + /** + Calls the static GetInternalName() function for the archive entry type, + for example + wxZipEntry::GetInternalName. + */ + wxString GetInternalName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the wxFileSystem protocol supported by this factory. Equivalent + to wxString(*GetProtcols()). + */ + wxString GetProtocol(); + + /** + Returns the protocols, MIME types or file extensions supported by this + factory, as an array of null terminated strings. It does not give away + ownership of the array or strings. + + For example, to list the file extensions a factory supports: + */ + const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL); + + /** + Create a new wxArchiveEntry object of the + appropriate type. + */ + wxArchiveEntry* NewEntry(); + + //@{ + /** + Create a new input or output stream to read or write an archive. + + If the parent stream is passed as a pointer then the new archive stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxArchiveInputStream* NewStream(wxInputStream& stream); + wxArchiveOutputStream* NewStream(wxOutputStream& stream); + wxArchiveInputStream* NewStream(wxInputStream* stream); + wxArchiveOutputStream* NewStream(wxOutputStream* stream); + //@} + + /** + Adds this class factory to the list returned + by @ref getfirst() GetFirst()/GetNext. + + It is not necessary to do this to use the archive streams. It is usually + used when implementing streams, typically the implementation will + add a static instance of its factory class. + + It can also be used to change the order of a factory already in the list, + bringing it to the front. This isn't a thread safe operation + so can't be done when other threads are running that will be using the list. + + The list does not take ownership of the factory. + */ + void PushFront(); + + /** + Removes this class factory from the list returned + by @ref getfirst() GetFirst()/GetNext. + + Removing from the list isn't a thread safe operation + so can't be done when other threads are running that will be using the list. + + The list does not own the factories, so removing a factory does not delete it. + */ + void Remove(); +}; + + +/** + @class wxArchiveNotifier + @wxheader{archive.h} + + If you need to know when a + wxArchiveInputStream updates a + wxArchiveEntry object, you can create + a notifier by deriving from this abstract base class, overriding + wxArchiveNotifier::OnEntryUpdated. An instance + of your notifier class can then be assigned to the wxArchiveEntry object + using wxArchiveEntry::SetNotifier. + Your OnEntryUpdated() method will then be invoked whenever the input + stream updates the entry. + + Setting a notifier is not usually necessary. It is used to handle + certain cases when modifying an archive in a pipeline (i.e. between + non-seekable streams). + See @ref overview_wxarcnoseek "Archives on non-seekable streams". + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarcnoseek "Archives on non-seekable streams", wxArchiveEntry, + wxArchiveInputStream, wxArchiveOutputStream +*/ +class wxArchiveNotifier +{ +public: + /** + This method must be overridden in your derived class. + */ + void OnEntryUpdated(class wxArchiveEntry& entry); +}; + + +/** + @class wxArchiveIterator + @wxheader{archive.h} + + An input iterator template class that can be used to transfer an archive's + catalogue to a container. It is only available if wxUSE_STL is set to 1 + in setup.h, and the uses for it outlined below require a compiler which + supports member templates. + + @code + template class Arc, class T = typename Arc::entry_type* + class wxArchiveIterator + { + // this constructor creates an 'end of sequence' object + wxArchiveIterator(); + + // template parameter 'Arc' should be the type of an archive input stream + wxArchiveIterator(Arc& arc) { + + /* ... */ + }; + @endcode + + The first template parameter should be the type of archive input stream + (e.g. wxArchiveInputStream) and the + second can either be a pointer to an entry + (e.g. wxArchiveEntry*), or a string/pointer pair + (e.g. std::pairwxString, wxArchiveEntry*). + + The @c wx/archive.h header defines the following typedefs: + + @code + typedef wxArchiveIteratorwxArchiveInputStream wxArchiveIter; + + typedef wxArchiveIteratorwxArchiveInputStream, + std::pairwxString, wxArchiveEntry* wxArchivePairIter; + @endcode + + The header for any implementation of this interface should define similar + typedefs for its types, for example in @c wx/zipstrm.h there is: + + @code + typedef wxArchiveIteratorwxZipInputStream wxZipIter; + + typedef wxArchiveIteratorwxZipInputStream, + std::pairwxString, wxZipEntry* wxZipPairIter; + @endcode + + Transferring the catalogue of an archive @e arc to a vector @e cat, + can then be done something like this: + + @code + std::vectorwxArchiveEntry* cat((wxArchiveIter)arc, wxArchiveIter()); + @endcode + + When the iterator is dereferenced, it gives away ownership of an entry + object. So in the above example, when you have finished with @e cat + you must delete the pointers it contains. + + If you have smart pointers with normal copy semantics (i.e. not auto_ptr + or wxScopedPtr), then you can create an iterator + which uses them instead. For example, with a smart pointer class for + zip entries @e ZipEntryPtr: + + @code + typedef std::vectorZipEntryPtr ZipCatalog; + typedef wxArchiveIteratorwxZipInputStream, ZipEntryPtr ZipIter; + ZipCatalog cat((ZipIter)zip, ZipIter()); + @endcode + + Iterators that return std::pair objects can be used to + populate a std::multimap, to allow entries to be looked + up by name. The string is initialised using the wxArchiveEntry object's + wxArchiveEntry::GetInternalName function. + + @code + typedef std::multimapwxString, wxZipEntry* ZipCatalog; + ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter()); + @endcode + + + Note that this iterator also gives away ownership of an entry + object each time it is dereferenced. So in the above example, when + you have finished with @e cat you must delete the pointers it contains. + + Or if you have them, a pair containing a smart pointer can be used + (again @e ZipEntryPtr), no worries about ownership: + + @code + typedef std::multimapwxString, ZipEntryPtr ZipCatalog; + typedef wxArchiveIteratorwxZipInputStream, + std::pairwxString, ZipEntryPtr ZipPairIter; + ZipCatalog cat((ZipPairIter)zip, ZipPairIter()); + @endcode + + @library{wxbase} + @category{FIXME} + + @seealso + wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream +*/ +class wxArchiveIterator +{ +public: + //@{ + /** + Construct iterator that returns all the entries in the archive input + stream @e arc. + */ + wxArchiveIterator(); + wxArchiveIterator(Arc& arc); + //@} + + /** + Returns an entry object from the archive input stream, giving away + ownership. + */ + const T operator*(); + + //@{ + /** + Position the input iterator at the next entry in the archive input stream. + */ + wxArchiveIterator operator++(); + wxArchiveIterator operator++(int ); + //@} +}; diff --git a/interface/arrstr.h b/interface/arrstr.h new file mode 100644 index 0000000000..85e99edfba --- /dev/null +++ b/interface/arrstr.h @@ -0,0 +1,269 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: arrstr.h +// Purpose: documentation for wxArrayString class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxArrayString + @wxheader{arrstr.h} + + wxArrayString is an efficient container for storing + wxString objects. It has the same features as all + wxArray classes, i.e. it dynamically expands when new items + are added to it (so it is as easy to use as a linked list), but the access + time to the elements is constant, instead of being linear in number of + elements as in the case of linked lists. It is also very size efficient and + doesn't take more space than a C array @e wxString[] type (wxArrayString + uses its knowledge of internals of wxString class to achieve this). + + This class is used in the same way as other dynamic arrays, + except that no @e WX_DEFINE_ARRAY declaration is needed for it. When a + string is added or inserted in the array, a copy of the string is created, so + the original string may be safely deleted (e.g. if it was a @e wxChar * + pointer the memory it was using can be freed immediately after this). In + general, there is no need to worry about string memory deallocation when using + this class - it will always free the memory it uses itself. + + The references returned by wxArrayString::Item, + wxArrayString::Last or + @ref wxArrayString::operatorindex operator[] are not constant, so the + array elements may be modified in place like this + + @code + array.Last().MakeUpper(); + @endcode + + 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 + wxArrayString::Index function (instead of linear search for + wxArrayString::Index) which makes it much more efficient if you add strings to + the array rarely (because, of course, you have to pay for Index() efficiency + by having Add() be slower) but search for them often. Several methods should + not be used with sorted array (basically, all 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. + + @library{wxbase} + @category{containers} + + @seealso + wxArray, wxString, @ref overview_wxstringoverview "wxString overview" +*/ +class wxArrayString : public wxArray +{ +public: + //@{ + /** + Constructor from a wxString array. Pass a size @e sz and array @e arr. + */ + wxArrayString(); + wxArrayString(const wxArrayString& array); + wxArrayString(size_t sz, const char** arr); + wxArrayString(size_t sz, const wchar_t** arr); + wxArrayString(size_t sz, const wxString* 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. + */ + ~wxArrayString(); + + /** + Appends the given number of @e copies of the new item @e str to the + array and returns the index of the first new item in the array. + + @b 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() + */ +#define size_t Add(const wxString& str, size_t copies = 1) /* implementation is private */ + + /** + Preallocates enough memory to store @e nCount items. This function may be + used to improve array class performance before adding a known number of items + consecutively. + + See also: @ref wxArray::memorymanagement "Dynamic array memory management" + */ + void Alloc(size_t nCount); + + /** + Clears the array contents and frees memory. + + See also: Empty() + */ + void Clear(); + + /** + Empties the array: after a call to this function + GetCount() will return 0. However, this + function does not free the memory used by the array and so should be used when + the array is going to be reused for storing other strings. Otherwise, you + should use Clear() to empty the array and free + memory. + */ + void Empty(); + + /** + Returns the number of items in the array. + */ + size_t GetCount(); + + /** + Search the element in the array, starting from the beginning if + @e bFromEnd is @false or from end otherwise. If @e 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 @e bCase and @e bFromEnd + parameters in the latter case. + + Returns index of the first item matched or @c wxNOT_FOUND if there is no match. + */ + int Index(const wxString& sz, bool bCase = @true, + bool bFromEnd = @false); + + /** + Insert the given number of @e copies of the new element in the array before the + position @e nIndex. Thus, for + example, to insert the string in the beginning of the array you would write + If @e nIndex is equal to @e GetCount() this function behaves as + Add(). + + @b Warning: this function should not be used with sorted arrays because it + could break the order of items and, for example, subsequent calls to + Index() would then not work! + */ + void Insert(const wxString& str, size_t nIndex, + size_t copies = 1); + + /** + Returns @true if the array is empty, @false otherwise. This function returns the + same result as @e GetCount() == 0 but is probably easier to read. + */ + bool IsEmpty(); + + /** + Return the array element at position @e 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 @ref operatorindex() operator[] for the operator + version. + */ + wxString Item(size_t nIndex); + + /** + Returns the last element of the array. Attempt to access the last element of + an empty array will result in assert failure in debug build, however no checks + are done in release mode. + */ + wxString Last(); + + /** + 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() + */ + void Remove(const wxString& sz); + + /** + Removes @e count items starting at position @e nIndex from the array. + */ + void RemoveAt(size_t nIndex, size_t count = 1); + + /** + Releases the extra memory allocated by the array. This function is useful to + minimize the array memory consumption. + + See also: Alloc(), @ref wxArray::memorymanagement "Dynamic array memory + management" + */ + void Shrink(); + + //@{ + /** + Sorts the array using the specified @e compareFunction for item comparison. + @e CompareFunction is defined as a function taking two @e const + wxString parameters and returning an @e int value less than, equal to or + greater than 0 if the first string is less than, equal to or greater than the + second one. + */ + void Sort(bool reverseOrder = @false); + Warning: void Sort(CompareFunction compareFunction); + //@} + + /** + Compares 2 arrays respecting the case. Returns @true if the arrays have + different number of elements or if the elements don't match pairwise. + */ + bool operator !=(const wxArrayString& array); + + /** + Assignment operator. + */ + wxArrayString operator =(const wxArrayString& array); + + /** + Compares 2 arrays respecting the case. Returns @true only if the arrays have + the same number of elements and the same strings in the same order. + */ + bool operator ==(const wxArrayString& array); + + /** + Return the array element at position @e 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. + */ + wxString operator[](size_t nIndex); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Splits the given wxString object using the separator @e sep and returns the + result as a wxArrayString. + + If the @e escape character is non-@NULL, then the occurrences of @e sep + immediately prefixed + with @e escape are not considered as separators. + + Note that empty tokens will be generated if there are two or more adjacent + separators. + + @sa wxJoin +*/ +wxArrayString wxSplit(const wxString& str, const wxChar sep, + const wxChar escape = ' +'); + +/** + Concatenate all lines of the given wxArrayString object using the separator @e + sep and returns + the result as a wxString. + + If the @e escape character is non-@NULL, then it's used as prefix for each + occurrence of @e sep + in the strings contained in @e arr before joining them which is necessary + in order to be able to recover the original array contents from the string + later using wxSplit. +*/ +wxString wxJoin(const wxArrayString& arr, const wxChar sep, + const wxChar escape = '\'); + diff --git a/interface/artprov.h b/interface/artprov.h new file mode 100644 index 0000000000..d46f0d8ae7 --- /dev/null +++ b/interface/artprov.h @@ -0,0 +1,342 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: artprov.h +// Purpose: documentation for wxArtProvider class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxArtProvider + @wxheader{artprov.h} + + wxArtProvider class is used to customize the look of wxWidgets application. + When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file + dialog), it does not use a hard-coded resource but asks wxArtProvider for it + instead. This way users can plug in their own wxArtProvider class and easily + replace standard art with their own version. All + that is needed is to derive a class from wxArtProvider, override either its + wxArtProvider::CreateBitmap and/or its + wxArtProvider::CreateIconBundle methods + and register the provider with + wxArtProvider::Push: + + @code + class MyProvider : public wxArtProvider + { + protected: + wxBitmap CreateBitmap(const wxArtID& id, + const wxArtClient& client, + const wxSize size) + + // optionally override this one as well + wxIconBundle CreateIconBundle(const wxArtID& id, + const wxArtClient& client) + { ... } + }; + ... + wxArtProvider::Push(new MyProvider); + @endcode + + If you need bitmap images (of the same artwork) that should be displayed at + different sizes + you should probably consider overriding wxArtProvider::CreateIconBundle + and supplying icon bundles that contain different bitmap sizes. + + There's another way of taking advantage of this class: you can use it in your + code and use + platform native icons as provided by wxArtProvider::GetBitmap or + wxArtProvider::GetIcon (NB: this is not yet really + possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too + small). + + + wxArtProvider::~wxArtProvider + wxArtProvider::CreateBitmap + wxArtProvider::CreateIconBundle + wxArtProvider::Delete + wxArtProvider::GetBitmap + wxArtProvider::GetIconBundle + wxArtProvider::GetIcon + wxArtProvider::Insert + wxArtProvider::Pop + wxArtProvider::Push + wxArtProvider::Remove + + + Identifying art resources + + Every bitmap and icon bundle are known to wxArtProvider under an unique ID that + is used when + requesting a resource from it. The ID is represented by wxArtID type and can + have one of these predefined values (you can see bitmaps represented by these + constants in the artprov sample): + + wxART_ERROR + wxART_QUESTION + wxART_WARNING + wxART_INFORMATION + wxART_ADD_BOOKMARK + wxART_DEL_BOOKMARK + wxART_HELP_SIDE_PANEL + wxART_HELP_SETTINGS + wxART_HELP_BOOK + wxART_HELP_FOLDER + wxART_HELP_PAGE + wxART_GO_BACK + wxART_GO_FORWARD + wxART_GO_UP + wxART_GO_DOWN + wxART_GO_TO_PARENT + wxART_GO_HOME + wxART_PRINT + wxART_HELP + wxART_TIP + wxART_REPORT_VIEW + wxART_LIST_VIEW + wxART_NEW_DIR + wxART_FOLDER + wxART_FOLDER_OPEN + wxART_GO_DIR_UP + wxART_EXECUTABLE_FILE + wxART_NORMAL_FILE + wxART_TICK_MARK + wxART_CROSS_MARK + wxART_MISSING_IMAGE + wxART_NEW + wxART_FILE_OPEN + wxART_FILE_SAVE + wxART_FILE_SAVE_AS + wxART_DELETE + wxART_COPY + wxART_CUT + wxART_PASTE + wxART_UNDO + wxART_REDO + wxART_QUIT + wxART_FIND + wxART_FIND_AND_REPLACE + wxART_HARDDISK + wxART_FLOPPY + wxART_CDROM + wxART_REMOVABLE + + + Additionally, any string recognized by custom art providers registered using + wxArtProvider::Push may be used. + + @library{wxcore} + @category{FIXME} + + @seealso + See the artprov sample for an example of wxArtProvider usage. +*/ +class wxArtProvider : public wxObject +{ +public: + /** + The destructor automatically removes the provider from the provider stack used + by GetBitmap(). + */ + ~wxArtProvider(); + + /** + 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: + + wxART_TOOLBAR + wxART_MENU + wxART_BUTTON + wxART_FRAME_ICON + wxART_CMN_DIALOG + wxART_HELP_BROWSER + wxART_MESSAGE_BOX + wxART_OTHER (used for all requests that don't fit into any of the categories + above) + + Client ID servers as a hint to wxArtProvider that is supposed to help it to + choose the best looking bitmap. For example it is often desirable to use + slightly different icons in menus and toolbars even though they represent the + same action (e.g. @c wx_ART_FILE_OPEN). Remember that this is really + only a hint for wxArtProvider -- it is common that + GetBitmap() + returns identical bitmap for different @e client values! + + @sa See the artprov sample for an example of wxArtProvider usage. + */ + + + /** + Derived art provider classes must override this method to create requested art + resource. Note that returned bitmaps are cached by wxArtProvider and it is + therefore not necessary to optimize CreateBitmap() for speed (e.g. you may + create wxBitmap objects from XPMs here). + + @param id + wxArtID unique identifier of the bitmap. + + @param client + wxArtClient identifier of the client (i.e. who is asking for the bitmap). + This only servers as a hint. + + @param size + Preferred size of the bitmap. The function may return a bitmap of different + dimensions, it will be automatically rescaled to meet client's request. + + @sa CreateIconBundle() + */ + wxBitmap CreateBitmap(const wxArtID& id, + const wxArtClient& client, + const wxSize& size); + + /** + This method is similar to CreateBitmap() but + can be used when a bitmap (or an icon) exists in several sizes. + */ + wxIconBundle CreateIconBundle(const wxArtID& id, + const wxArtClient& client); + + /** + Delete the given @e provider. + */ + static bool Delete(wxArtProvider* provider); + + /** + Query registered providers for bitmap with given ID. + + @param id + wxArtID unique identifier of the bitmap. + + @param client + wxArtClient identifier of the client (i.e. who is asking for the bitmap). + + @param size + Size of the returned bitmap or wxDefaultSize if size doesn't matter. + + @returns The bitmap if one of registered providers recognizes the ID or + wxNullBitmap otherwise. + */ + static wxBitmap GetBitmap(const wxArtID& id, + const wxArtClient& client = wxART_OTHER, + const wxSize& size = wxDefaultSize); + + //@{ + /** + Returns a suitable size hint for the given @e wxArtClient. If + @e platform_default is @true, return a size based on the current platform, + otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may + be + returned if the client doesn't have a specified size, like wxART_OTHER for + example. + */ + static wxIcon GetIcon(const wxArtID& id, + const wxArtClient& client = wxART_OTHER, + const wxSize& size = wxDefaultSize); + static wxSize GetSizeHint(const wxArtClient& client, + bool platform_default = @false); + //@} + + /** + Query registered providers for icon bundle with given ID. + + @param id + wxArtID unique identifier of the icon bundle. + + @param client + wxArtClient identifier of the client (i.e. who is asking for the icon bundle). + + @returns The icon bundle if one of registered providers recognizes the ID + or wxNullIconBundle otherwise. + */ + static wxIconBundle GetIconBundle(const wxArtID& id, + const wxArtClient& client = wxART_OTHER); + + /** + Every bitmap and icon bundle are known to wxArtProvider under an unique ID that + is used when + requesting a resource from it. The ID is represented by wxArtID type and can + have one of these predefined values (you can see bitmaps represented by these + constants in the artprov sample): + + wxART_ERROR + wxART_QUESTION + wxART_WARNING + wxART_INFORMATION + wxART_ADD_BOOKMARK + wxART_DEL_BOOKMARK + wxART_HELP_SIDE_PANEL + wxART_HELP_SETTINGS + wxART_HELP_BOOK + wxART_HELP_FOLDER + wxART_HELP_PAGE + wxART_GO_BACK + wxART_GO_FORWARD + wxART_GO_UP + wxART_GO_DOWN + wxART_GO_TO_PARENT + wxART_GO_HOME + wxART_PRINT + wxART_HELP + wxART_TIP + wxART_REPORT_VIEW + wxART_LIST_VIEW + wxART_NEW_DIR + wxART_FOLDER + wxART_FOLDER_OPEN + wxART_GO_DIR_UP + wxART_EXECUTABLE_FILE + wxART_NORMAL_FILE + wxART_TICK_MARK + wxART_CROSS_MARK + wxART_MISSING_IMAGE + wxART_NEW + wxART_FILE_OPEN + wxART_FILE_SAVE + wxART_FILE_SAVE_AS + wxART_DELETE + wxART_COPY + wxART_CUT + wxART_PASTE + wxART_UNDO + wxART_REDO + wxART_QUIT + wxART_FIND + wxART_FIND_AND_REPLACE + wxART_HARDDISK + wxART_FLOPPY + wxART_CDROM + wxART_REMOVABLE + + Additionally, any string recognized by custom art providers registered using + Push() may be used. + */ + + + /** + Register new art provider and add it to the bottom of providers stack (i.e. + it will be queried as the last one). + + @sa Push() + */ + static void Insert(wxArtProvider* provider); + + /** + Remove latest added provider and delete it. + */ +#define static bool Pop() /* implementation is private */ + + /** + Register new art provider and add it to the top of providers stack (i.e. it + will be queried as the first provider). + + @sa Insert() + */ + static void Push(wxArtProvider* provider); + + /** + Remove a provider from the stack if it is on it. The provider is not + deleted, unlike when using Delete(). + */ + static bool Remove(wxArtProvider* provider); +}; diff --git a/interface/atomic.h b/interface/atomic.h new file mode 100644 index 0000000000..1e535a3a38 --- /dev/null +++ b/interface/atomic.h @@ -0,0 +1,15 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: atomic.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + This function increments @e value in an atomic manner. +*/ +void wxAtomicInc(wxAtomicInt& value); + + + \ No newline at end of file diff --git a/interface/aui/aui.h b/interface/aui/aui.h new file mode 100644 index 0000000000..d6698c896d --- /dev/null +++ b/interface/aui/aui.h @@ -0,0 +1,689 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: aui/aui.h +// Purpose: documentation for wxAuiManager class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAuiManager + @headerfile aui.h wx/aui/aui.h + + wxAuiManager is the central class of the wxAUI class framework. + + See also @ref overview_wxauioverview "wxAUI overview". + + wxAuiManager manages the panes associated with it + for a particular wxFrame, using a pane's wxAuiPaneInfo information to + determine each pane's docking and floating behavior. wxAuiManager + uses wxWidgets' sizer mechanism to plan the layout of each frame. It + uses a replaceable dock art class to do all drawing, so all drawing is + localized in one area, and may be customized depending on an + application's specific needs. + + wxAuiManager works as follows: the programmer adds panes to the class, + or makes changes to existing pane properties (dock position, floating + state, show state, etc.). To apply these changes, wxAuiManager's + Update() function is called. This batch processing can be used to avoid + flicker, by modifying more than one pane at a time, and then "committing" + all of the changes at once by calling Update(). + + Panes can be added quite easily: + + @code + wxTextCtrl* text1 = new wxTextCtrl(this, -1); + wxTextCtrl* text2 = new wxTextCtrl(this, -1); + m_mgr.AddPane(text1, wxLEFT, wxT("Pane Caption")); + m_mgr.AddPane(text2, wxBOTTOM, wxT("Pane Caption")); + m_mgr.Update(); + @endcode + + Later on, the positions can be modified easily. The following will float + an existing pane in a tool window: + + @code + m_mgr.GetPane(text1).Float(); + @endcode + + @library{wxbase} + @category{aui} + + @seealso + wxAuiPaneInfo, wxAuiDockArt +*/ +class wxAuiManager : public wxEvtHandler +{ +public: + /** + Constructor. @e managed_wnd specifies the wxFrame which should be managed. + @e flags specifies options which allow the frame management behavior + to be modified. + */ + wxAuiManager(wxWindow* managed_wnd = @NULL, + unsigned int flags = wxAUI_MGR_DEFAULT); + + /** + + */ + ~wxAuiManager(); + + //@{ + /** + AddPane() tells the frame manager to start managing a child window. There are + several versions of this function. The first version allows the full spectrum of pane parameter possibilities. The second version is used for simpler user interfaces which do not require as much configuration. The last version allows a drop position to be specified, which will determine where the pane will be added. + */ + bool AddPane(wxWindow* window, const wxAuiPaneInfo& pane_info); + bool AddPane(wxWindow* window, int direction = wxLEFT, + const wxString& caption = wxEmptyString); + bool AddPane(wxWindow* window, + const wxAuiPaneInfo& pane_info, + const wxPoint& drop_pos); + //@} + + /** + Tells the wxAuiManager to stop managing the pane specified by window. + The window, if in a floated frame, is reparented to the frame managed + by wxAuiManager. + */ + bool DetachPane(wxWindow* window); + + /** + Returns an array of all panes managed by the frame manager. + */ + wxAuiPaneInfoArray GetAllPanes(); + + /** + Returns the current art provider being used. + + See also: wxAuiDockArt. + */ + wxAuiDockArt* GetArtProvider(); + + /** + Returns the current dock constraint values. See SetDockSizeConstraint() for + more information. + */ + void GetDockSizeConstraint(double* widthpct, double* heightpct); + + /** + Returns the current manager's flags. + */ + unsigned int GetFlags(); + + /** + Returns the frame currently being managed by wxAuiManager. + */ + wxWindow* GetManagedWindow(); + + /** + Calling this method will return the wxAuiManager for a given window. The @e + window parameter should + specify any child window or sub-child window of the frame or window managed by + wxAuiManager. + The @e window parameter need not be managed by the manager itself, nor does it + even need to be a child + or sub-child of a managed window. It must however be inside the window + hierarchy underneath the managed + window. + */ + static wxAuiManager* GetManager(wxWindow* window); + + //@{ + /** + @e GetPane is used to lookup a wxAuiPaneInfo object + either by window pointer or by pane name, which acts as a unique id for + a window pane. The returned wxAuiPaneInfo object may then be modified to + change a pane's look, state or position. After one or more + modifications to wxAuiPaneInfo, wxAuiManager::Update() should be called + to commit the changes to the user interface. If the lookup failed + (meaning the pane could not be found in the manager), a call to the + returned wxAuiPaneInfo's IsOk() method will return @false. + */ + wxAuiPaneInfo GetPane(wxWindow* window); + wxAuiPaneInfo GetPane(const wxString& name); + //@} + + /** + HideHint() hides any docking hint that may be visible. + */ + void HideHint(); + + /** + This method is used to insert either a previously unmanaged pane window + into the frame manager, or to insert a currently managed pane somewhere + else. @e InsertPane will push all panes, rows, or docks aside and + insert the window into the position specified by @e insert_location. + Because @e insert_location can specify either a pane, dock row, or dock + layer, the @e insert_level parameter is used to disambiguate this. The + parameter @e insert_level can take a value of wxAUI_INSERT_PANE, + wxAUI_INSERT_ROW + or wxAUI_INSERT_DOCK. + */ + bool InsertPane(wxWindow* window, + const wxAuiPaneInfo& insert_location, + int insert_level = wxAUI_INSERT_PANE); + + /** + LoadPaneInfo() is similar to to LoadPerspective, with the exception that it + only loads information about a single pane. It is used in combination with SavePaneInfo(). + */ + void LoadPaneInfo(wxString pane_part, wxAuiPaneInfo& pane); + + /** + Loads a saved perspective. If update is @true, wxAuiManager::Update() + is automatically invoked, thus realizing the saved perspective on screen. + */ + bool LoadPerspective(const wxString& perspective, + bool update = @true); + + /** + ProcessDockResult() is a protected member of the wxAUI layout manager. It can + be overridden by derived classes to provide custom docking calculations. + */ + bool ProcessDockResult(wxAuiPaneInfo& target, + const wxAuiPaneInfo& new_pos); + + /** + SavePaneInfo() is similar to SavePerspective, with the exception that it only + saves information about a single pane. It is used in combination with LoadPaneInfo(). + */ + wxString SavePaneInfo(wxAuiPaneInfo& pane); + + /** + Saves the entire user interface layout into an encoded wxString, which + can then be stored by the application (probably using wxConfig). When + a perspective is restored using LoadPerspective(), the entire user + interface will return to the state it was when the perspective was saved. + */ + wxString SavePerspective(); + + /** + Instructs wxAuiManager to use art provider specified by parameter + @e art_provider for all drawing calls. This allows plugable + look-and-feel features. The previous art provider object, if any, + will be deleted by wxAuiManager. + + See also: wxAuiDockArt. + */ + void SetArtProvider(wxAuiDockArt* art_provider); + + /** + When a user creates a new dock by dragging a window into a docked position, + often times the large size of the + window will create a dock that is unwieldly large. wxAuiManager by default + limits the size of any + new dock to 1/3 of the window size. For horizontal docks, this would be 1/3 of + the window height. For + vertical docks, 1/3 of the width. Calling this function will adjust this + constraint value. The numbers + must be between 0.0 and 1.0. For instance, calling SetDockSizeContraint with + 0.5, 0.5 will cause new + docks to be limited to half of the size of the entire managed window. + */ + void SetDockSizeConstraint(double widthpct, double heightpct); + + /** + This method is used to specify wxAuiManager's settings flags. @e flags + specifies options which allow the frame management behavior to be modified. + */ + void SetFlags(unsigned int flags); + + /** + Called to specify the frame or window which is to be managed by wxAuiManager. + Frame management is not restricted to just frames. Child windows or custom controls are also allowed. + */ + void SetManagedWindow(wxWindow* managed_wnd); + + /** + This function is used by controls to explicitly show a hint window at the + specified rectangle. It is rarely called, and is mostly used by controls implementing custom pane drag/drop behaviour. The specified rectangle should be in screen coordinates. + */ + void ShowHint(const wxRect& rect); + + /** + Uninitializes the framework and should be called before a managed frame or + window is destroyed. UnInit() is usually called in the managed wxFrame's destructor. It is necessary to call this function before the managed frame or window is destroyed, otherwise the manager cannot remove its custom event handlers from a window. + */ + void UnInit(); + + /** + This method is called after any number of changes are + made to any of the managed panes. Update() must be invoked after + AddPane() or InsertPane() are called in order to "realize" or "commit" + the changes. In addition, any number of changes may be made to + wxAuiPaneInfo structures (retrieved with wxAuiManager::GetPane), but to + realize the changes, Update() must be called. This construction allows + pane flicker to be avoided by updating the whole layout at one time. + */ + void Update(); +}; + + +/** + @class wxAuiPaneInfo + @headerfile aui.h wx/aui/aui.h + + wxAuiPaneInfo is part of the wxAUI class framework. + See also @ref overview_wxauioverview "wxAUI overview". + + wxAuiPaneInfo specifies all the parameters for a pane. + These parameters specify where the pane is on the + screen, whether it is docked or floating, or hidden. + In addition, these parameters specify the pane's + docked position, floating position, preferred size, + minimum size, caption text among many other parameters. + + @library{wxbase} + @category{aui} + + @seealso + wxAuiManager, wxAuiDockArt +*/ +class wxAuiPaneInfo +{ +public: + //@{ + /** + Copy constructor. + */ + wxAuiPaneInfo(); + wxAuiPaneInfo(const wxAuiPaneInfo& c); + //@} + + //@{ + /** + BestSize() sets the ideal size for the pane. The docking manager will attempt + to use this size as much as possible when docking or floating the pane. + */ + wxAuiPaneInfo BestSize(const wxSize& size); + wxAuiPaneInfo BestSize(int x, int y); + //@} + + /** + Bottom() sets the pane dock position to the bottom side of the frame. This is + the same thing as calling Direction(wxAUI_DOCK_BOTTOM). + */ + wxAuiPaneInfo Bottom(); + + /** + BottomDockable() indicates whether a pane can be docked at the bottom of the + frame. + */ + wxAuiPaneInfo BottomDockable(bool b = @true); + + /** + Caption() sets the caption of the pane. + */ + wxAuiPaneInfo Caption(const wxString& c); + + /** + CaptionVisible indicates that a pane caption should be visible. If @false, no + pane caption is drawn. + */ + wxAuiPaneInfo CaptionVisible(bool visible = @true); + + //@{ + /** + Center() sets the pane dock position to the left side of the frame. + The centre pane is the space in the middle after all border panes (left, top, + right, bottom) are subtracted from the layout. + + This is the same thing as calling Direction(wxAUI_DOCK_CENTRE). + */ + wxAuiPaneInfo Centre(); + wxAuiPaneInfo Center(); + //@} + + //@{ + /** + CentrePane() specifies that the pane should adopt the default center pane + settings. Centre panes usually do not have caption bars. This function provides an easy way of preparing a pane to be displayed in the center dock position. + */ + wxAuiPaneInfo CentrePane(); + wxAuiPaneInfo CenterPane(); + //@} + + /** + CloseButton() indicates that a close button should be drawn for the pane. + */ + wxAuiPaneInfo CloseButton(bool visible = @true); + + /** + DefaultPane() specifies that the pane should adopt the default pane settings. + */ + wxAuiPaneInfo DefaultPane(); + + /** + DestroyOnClose() indicates whether a pane should be detroyed when it is closed. + Normally a pane is simply hidden when the close button is clicked. Setting DestroyOnClose to @true will cause the window to be destroyed when the user clicks the pane's close button. + */ + wxAuiPaneInfo DestroyOnClose(bool b = @true); + + /** + Direction() determines the direction of the docked pane. It is functionally the + same as calling Left(), Right(), Top() or Bottom(), except that docking direction may be specified programmatically via the parameter. + */ + wxAuiPaneInfo Direction(int direction); + + /** + Dock() indicates that a pane should be docked. It is the opposite of Float(). + */ + wxAuiPaneInfo Dock(); + + /** + DockFixed() causes the containing dock to have no resize sash. This is useful + for creating panes that span the entire width or height of a dock, but should not be resizable in the other direction. + */ + wxAuiPaneInfo DockFixed(bool b = @true); + + /** + Dockable() specifies whether a frame can be docked or not. It is the same as + specifying TopDockable(b).BottomDockable(b).LeftDockable(b).RightDockable(b). + */ + wxAuiPaneInfo Dockable(bool b = @true); + + /** + Fixed() forces a pane to be fixed size so that it cannot be resized. After + calling Fixed(), IsFixed() will return @true. + */ + wxAuiPaneInfo Fixed(); + + /** + Float() indicates that a pane should be floated. It is the opposite of Dock(). + */ + wxAuiPaneInfo Float(); + + /** + Floatable() sets whether the user will be able to undock a pane and turn it + into a floating window. + */ + wxAuiPaneInfo Floatable(bool b = @true); + + //@{ + /** + FloatingPosition() sets the position of the floating pane. + */ + wxAuiPaneInfo FloatingPosition(const wxPoint& pos); + wxAuiPaneInfo FloatingPosition(int x, int y); + //@} + + //@{ + /** + FloatingSize() sets the size of the floating pane. + */ + wxAuiPaneInfo FloatingSize(const wxSize& size); + wxAuiPaneInfo FloatingSize(int x, int y); + //@} + + /** + Gripper() indicates that a gripper should be drawn for the pane. + */ + wxAuiPaneInfo Gripper(bool visible = @true); + + /** + GripperTop() indicates that a gripper should be drawn at the top of the pane. + */ + wxAuiPaneInfo GripperTop(bool attop = @true); + + /** + HasBorder() returns @true if the pane displays a border. + */ + bool HasBorder(); + + /** + HasCaption() returns @true if the pane displays a caption. + */ + bool HasCaption(); + + /** + HasCloseButton() returns @true if the pane displays a button to close the pane. + */ + bool HasCloseButton(); + + /** + HasFlag() returns @true if the the property specified by flag is active for the + pane. + */ + bool HasFlag(unsigned int flag); + + /** + HasGripper() returns @true if the pane displays a gripper. + */ + bool HasGripper(); + + /** + HasGripper() returns @true if the pane displays a gripper at the top. + */ + bool HasGripperTop(); + + /** + HasMaximizeButton() returns @true if the pane displays a button to maximize the + pane. + */ + bool HasMaximizeButton(); + + /** + HasMinimizeButton() returns @true if the pane displays a button to minimize the + pane. + */ + bool HasMinimizeButton(); + + /** + HasPinButton() returns @true if the pane displays a button to float the pane. + */ + bool HasPinButton(); + + /** + Hide() indicates that a pane should be hidden. + */ + wxAuiPaneInfo Hide(); + + /** + IsBottomDockable() returns @true if the pane can be docked at the bottom of the + managed frame. + */ + bool IsBottomDockable(); + + /** + IsDocked() returns @true if the pane is docked. + */ + bool IsDocked(); + + /** + IsFixed() returns @true if the pane cannot be resized. + */ + bool IsFixed(); + + /** + IsFloatable() returns @true if the pane can be undocked and displayed as a + floating window. + */ + bool IsFloatable(); + + /** + IsFloating() returns @true if the pane is floating. + */ + bool IsFloating(); + + /** + IsLeftDockable() returns @true if the pane can be docked on the left of the + managed frame. + */ + bool IsLeftDockable(); + + /** + IsMoveable() returns @true if the docked frame can be undocked or moved to + another dock position. + */ + bool IsMovable(); + + /** + IsOk() returns @true if the wxAuiPaneInfo structure is valid. A pane structure + is valid if it has an associated window. + */ +#define bool IsOk() /* implementation is private */ + + /** + IsResizable() returns @true if the pane can be resized. + */ + bool IsResizable(); + + /** + IsRightDockable() returns @true if the pane can be docked on the right of the + managed frame. + */ + bool IsRightDockable(); + + /** + IsShown() returns @true if the pane is currently shown. + */ + bool IsShown(); + + /** + IsToolbar() returns @true if the pane contains a toolbar. + */ + bool IsToolbar(); + + /** + IsTopDockable() returns @true if the pane can be docked at the top of the + managed frame. + */ + bool IsTopDockable(); + + /** + Layer() determines the layer of the docked pane. The dock layer is similar to + an onion, the inner-most layer being layer 0. Each shell moving in the outward direction has a higher layer number. This allows for more complex docking layout formation. + */ + wxAuiPaneInfo Layer(int layer); + + /** + Left() sets the pane dock position to the left side of the frame. This is the + same thing as calling Direction(wxAUI_DOCK_LEFT). + */ + wxAuiPaneInfo Left(); + + /** + LeftDockable() indicates whether a pane can be docked on the left of the frame. + */ + wxAuiPaneInfo LeftDockable(bool b = @true); + + //@{ + /** + MaxSize() sets the maximum size of the pane. + */ + wxAuiPaneInfo MaxSize(const wxSize& size); + wxAuiPaneInfo MaxSize(int x, int y); + //@} + + /** + MaximizeButton() indicates that a maximize button should be drawn for the pane. + */ + wxAuiPaneInfo MaximizeButton(bool visible = @true); + + //@{ + /** + MinSize() sets the minimum size of the pane. Please note that this is only + partially supported as of this writing. + */ + wxAuiPaneInfo MinSize(const wxSize& size); + wxAuiPaneInfo MinSize(int x, int y); + //@} + + /** + MinimizeButton() indicates that a minimize button should be drawn for the pane. + */ + wxAuiPaneInfo MinimizeButton(bool visible = @true); + + /** + Movable indicates whether a frame can be moved. + */ + wxAuiPaneInfo Movable(bool b = @true); + + /** + Name() sets the name of the pane so it can be referenced in lookup functions. + If a name is not specified by the user, a random name is assigned to the pane when it is added to the manager. + */ + wxAuiPaneInfo Name(const wxString& n); + + /** + PaneBorder indicates that a border should be drawn for the pane. + */ + wxAuiPaneInfo PaneBorder(bool visible = @true); + + /** + PinButton() indicates that a pin button should be drawn for the pane. + */ + wxAuiPaneInfo PinButton(bool visible = @true); + + /** + Position() determines the position of the docked pane. + */ + wxAuiPaneInfo Position(int pos); + + /** + Resizable() allows a pane to be resized if the parameter is @true, and forces it + to be a fixed size if the parameter is @false. This is simply an antonym for Fixed(). + */ + wxAuiPaneInfo Resizable(bool resizable = @true); + + /** + Right() sets the pane dock position to the right side of the frame. + */ + wxAuiPaneInfo Right(); + + /** + RightDockable() indicates whether a pane can be docked on the right of the + frame. + */ + wxAuiPaneInfo RightDockable(bool b = @true); + + /** + Row() determines the row of the docked pane. + */ +#define wxAuiPaneInfo Row(int row) /* implementation is private */ + + /** + Write the safe parts of a newly loaded PaneInfo structure "source" into "this" + used on loading perspectives etc. + */ + void SafeSet(wxAuiPaneInfo source); + + /** + SetFlag() turns the property given by flag on or off with the option_state + parameter. + */ + wxAuiPaneInfo SetFlag(unsigned int flag, bool option_state); + + /** + Show() indicates that a pane should be shown. + */ + wxAuiPaneInfo Show(bool show = @true); + + /** + ToolbarPane() specifies that the pane should adopt the default toolbar pane + settings. + */ + wxAuiPaneInfo ToolbarPane(); + + /** + Top() sets the pane dock position to the top of the frame. + */ +#define wxAuiPaneInfo Top() /* implementation is private */ + + /** + TopDockable() indicates whether a pane can be docked at the top of the frame. + */ + wxAuiPaneInfo TopDockable(bool b = @true); + + /** + Window() assigns the window pointer that the wxAuiPaneInfo should use. This + normally does not need to be specified, as the window pointer is automatically assigned to the wxAuiPaneInfo structure as soon as it is added to the manager. + */ + wxAuiPaneInfo Window(wxWindow* w); + + /** + Makes a copy of the wxAuiPaneInfo object. + */ + wxAuiPaneInfo& operator operator=(const wxAuiPaneInfo& c); +}; diff --git a/interface/aui/auibook.h b/interface/aui/auibook.h new file mode 100644 index 0000000000..b466056683 --- /dev/null +++ b/interface/aui/auibook.h @@ -0,0 +1,342 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: aui/auibook.h +// Purpose: documentation for wxAuiNotebook class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAuiNotebook + @headerfile auibook.h wx/aui/auibook.h + + wxAuiNotebook is part of the wxAUI class framework. + See also @ref overview_wxauioverview "wxAUI overview". + + wxAuiNotebook is a notebook control which implements many features common in + applications with dockable panes. + Specifically, wxAuiNotebook implements functionality which allows the user to + rearrange tab order via drag-and-drop, + split the tab window into many different splitter configurations, and toggle + through different themes to customize + the control's look and feel. + + An effort has been made to try to maintain an API as similar to that of + wxNotebook. + + The default theme that is used is wxAuiDefaultTabArt, which provides a modern, + glossy look and feel. + The theme can be changed by calling wxAuiNotebook::SetArtProvider. + + @beginStyleTable + @style{wxAUI_NB_DEFAULT_STYLE}: + Defined as wxAUI_NB_TOP | wxAUI_NB_TAB_SPLIT | wxAUI_NB_TAB_MOVE | + wxAUI_NB_SCROLL_BUTTONS | wxAUI_NB_CLOSE_ON_ACTIVE_TAB. + @style{wxAUI_NB_TAB_SPLIT}: + Allows the tab control to be split by dragging a tab. + @style{wxAUI_NB_TAB_MOVE}: + Allows a tab to be moved horizontally by dragging. + @style{wxAUI_NB_TAB_EXTERNAL_MOVE}: + Allows a tab to be moved to another tab control. + @style{wxAUI_NB_TAB_FIXED_WIDTH}: + With this style, all tabs have the same width. + @style{wxAUI_NB_SCROLL_BUTTONS}: + With this style, left and right scroll buttons are displayed. + @style{wxAUI_NB_WINDOWLIST_BUTTON}: + With this style, a drop-down list of windows is available. + @style{wxAUI_NB_CLOSE_BUTTON}: + With this style, a close button is available on the tab bar. + @style{wxAUI_NB_CLOSE_ON_ACTIVE_TAB}: + With this style, the close button is visible on the active tab. + @style{wxAUI_NB_CLOSE_ON_ALL_TABS}: + With this style, the close button is visible on all tabs. + @style{wxAUI_NB_TOP}: + With this style, tabs are drawn along the top of the notebook. + @style{wxAUI_NB_BOTTOM}: + With this style, tabs are drawn along the bottom of the notebook. + @endStyleTable + + @library{wxaui} + @category{aui} +*/ +class wxAuiNotebook : public wxControl +{ +public: + //@{ + /** + Constructor. Creates a wxAuiNotebok control. + */ + wxAuiNotebook(); + wxAuiNotebook(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxAUI_NB_DEFAULT_STYLE); + //@} + + /** + Adds a page. If the @e select parameter is @true, calling this will generate a + page change event. + */ + bool AddPage(wxWindow* page, const wxString& caption, + bool select = @false, + const wxBitmap& bitmap = wxNullBitmap); + + /** + Sets the selection to the next or previous page. + */ + void AdvanceSelection(bool forward = @true); + + /** + Creates the notebook window. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + + /** + Deletes a page at the given index. Calling this method will generate a page + change event. + */ + bool DeletePage(size_t page); + + /** + Returns the associated art provider. + */ + wxAuiTabArt* GetArtProvider(); + + /** + Returns the desired height of the notebook for the given page height. Use this + to fit the notebook to + a given page size. + */ + int GetHeightForPageHeight(int pageHeight); + + /** + Returns the page specified by the given index. + */ + wxWindow* GetPage(size_t page_idx); + + /** + Returns the tab bitmap for the page. + */ + wxBitmap GetPageBitmap(size_t page); + + /** + Returns the number of pages in the notebook. + */ + size_t GetPageCount(); + + /** + Returns the page index for the specified window. If the window is not found in + the notebook, wxNOT_FOUND is returned. + */ + int GetPageIndex(wxWindow* page_wnd); + + /** + Returns the tab label for the page. + */ + wxString GetPageText(size_t page); + + /** + Returns the currently selected page. + */ + int GetSelection(); + + /** + Returns the height of the tab control. + */ + int GetTabCtrlHeight(); + + /** + InsertPage() is similar to AddPage, but allows the ability to specify the + insert location. + If the @e select parameter is @true, calling this will generate a page change + event. + */ + bool InsertPage(size_t page_idx, wxWindow* page, + const wxString& caption, + bool select = @false, + const wxBitmap& bitmap = wxNullBitmap); + + /** + Removes a page, without deleting the window pointer. + */ + bool RemovePage(size_t page); + + /** + Sets the art provider to be used by the notebook. + */ + void SetArtProvider(wxAuiTabArt* art); + + /** + Sets the font for drawing the tab labels, using a bold version of the font for + selected tab labels. + */ + bool SetFont(const wxFont& font); + + /** + Sets the font for measuring tab labels. + */ + void SetMeasuringFont(const wxFont& font); + + /** + Sets the font for drawing unselected tab labels. + */ + void SetNormalFont(const wxFont& font); + + /** + Sets the bitmap for the page. To remove a bitmap from the tab caption, pass + wxNullBitmap. + */ + bool SetPageBitmap(size_t page, const wxBitmap& bitmap); + + /** + Sets the tab label for the page. + */ + bool SetPageText(size_t page, const wxString& text); + + /** + Sets the font for drawing selected tab labels. + */ + void SetSelectedFont(const wxFont& font); + + /** + Sets the page selection. Calling this method will generate a page change event. + */ + size_t SetSelection(size_t new_page); + + /** + Sets the tab height. By default, the tab control height is calculated + by measuring the text height and bitmap sizes on the tab captions. Calling this + method will override that calculation and set the tab control to the specified + height parameter. A call to this method will override any call to + SetUniformBitmapSize(). + Specifying -1 as the height will return the control to its default auto-sizing + behaviour. + */ + void SetTabCtrlHeight(int height); + + //@{ + /** + Split performs a split operation programmatically. The argument @e page + indicates + the page that will be split off. This page will also become the active page + after the + split. The @e direction argument specifies where the pane should go, it should + be one + of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT. + */ + void SetUniformBitmapSize(const wxSize& size); + void Split(size_t page, int direction); + //@} + + /** + Shows the window menu for the active tab control associated with this notebook, + and returns @true if a selection was made. + */ + bool ShowWindowMenu(); +}; + + +/** + @class wxAuiTabArt + @headerfile auibook.h wx/aui/auibook.h + + Tab art class. + + @library{wxaui} + @category{aui} +*/ +class wxAuiTabArt +{ +public: + /** + Constructor. + */ + wxAuiTabArt(); + + /** + Clones the art object. + */ + wxAuiTabArt* Clone(); + + /** + Draws a background on the given area. + */ + void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect); + + /** + Draws a button. + */ + void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect, + int bitmap_id, + int button_state, + int orientation, + const wxBitmap& bitmap_override, + wxRect* out_rect); + + /** + Draws a tab. + */ + void DrawTab(wxDC& dc, wxWindow* wnd, const wxRect& in_rect, + const wxString& caption, + const wxBitmap& bitmap, + bool active, + int close_button_state, + wxRect* out_tab_rect, + wxRect* out_button_rect, + int* x_extent); + + /** + Returns the tab control size. + */ + int GetBestTabCtrlSize(wxWindow* wnd, + wxAuiNotebookPageArray& pages); + + /** + Returns the indent size. + */ + int GetIndentSize(); + + /** + Returns the tab size for the given caption, bitmap and state. + */ + wxSize GetTabSize(wxDC& dc, wxWindow* wnd, + const wxString& caption, + const wxBitmap& bitmap, + bool active, + int close_button_state, + int* x_extent); + + /** + Sets flags. + */ + void SetFlags(unsigned int flags); + + /** + Sets the font used for calculating measurements. + */ + void SetMeasuringFont(const wxFont& font); + + /** + Sets the normal font for drawing labels. + */ + void SetNormalFont(const wxFont& font); + + /** + Sets the font for drawing text for selected UI elements. + */ + void SetSelectedFont(const wxFont& font); + + /** + Sets sizing information. + */ + void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count); + + /** + Pops up a menu to show the list of windows managed by wxAui. + */ + int ShowWindowList(wxWindow* wnd, const wxArrayString& items, + int active_idx); +}; diff --git a/interface/aui/dockart.h b/interface/aui/dockart.h new file mode 100644 index 0000000000..983c64c3c7 --- /dev/null +++ b/interface/aui/dockart.h @@ -0,0 +1,143 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: aui/dockart.h +// Purpose: documentation for wxAuiDockArt class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAuiDockArt + @headerfile dockart.h wx/aui/dockart.h + + wxAuiDockArt is part of the wxAUI class framework. + See also @ref overview_wxauioverview "wxAUI overview". + + Dock art provider code - a dock provider provides all drawing + functionality to the wxAui dock manager. This allows the dock + manager to have a plugable look-and-feel. + + By default, a wxAuiManager uses an + instance of this class called @b wxAuiDefaultDockArt which + provides bitmap art and a colour scheme that is adapted to + the major platforms' look. You can either derive from that + class to alter its behaviour or write a completely new dock + art class. Call wxAuiManager::SetArtProvider + to make use this new dock art. + + @library{wxaui} + @category{aui} + + @seealso + wxAuiManager, wxAuiPaneInfo +*/ +class wxAuiDockArt +{ +public: + /** + Constructor. + */ + wxAuiDockArt(); + + /** + Destructor. + */ + ~wxAuiDockArt(); + + /** + Draws a background. + */ + virtual void DrawBackground(wxDC& dc, wxWindow* window, + int orientation, + const wxRect& rect); + + /** + Draws a border. + */ + virtual void DrawBorder(wxDC& dc, wxWindow* window, + const wxRect& rect, + wxAuiPaneInfo& pane); + + /** + Draws a caption. + */ + virtual void DrawCaption(wxDC& dc, wxWindow* window, + const wxString& text, + const wxRect& rect, + wxAuiPaneInfo& pane); + + /** + Draws a gripper. + */ + virtual void DrawGripper(wxDC& dc, wxWindow* window, + const wxRect& rect, + wxAuiPaneInfo& pane); + + /** + Draws a button in the pane's title bar. + + @e button can be one of the values of @b wxAuiButtonId. + + @e button_state can be one of the values of @b wxAuiPaneButtonState. + */ + virtual void DrawPaneButton(wxDC& dc, wxWindow* window, + int button, + int button_state, + const wxRect& rect, + wxAuiPaneInfo& pane); + + /** + Draws a sash between two windows. + */ + virtual void DrawSash(wxDC& dc, wxWindow* window, + int orientation, + const wxRect& rect); + + /** + The same as GetColour(). + */ + virtual wxColour GetColor(int id); + + /** + Get the colour of a certain setting. + + @e id can be one of the colour values of @b wxAuiPaneDockArtSetting. + */ + virtual wxColour GetColour(int id); + + /** + Get a font setting. + */ + virtual wxFont GetFont(int id); + + /** + Get the value of a certain setting. + + @e id can be one of the size values of @b wxAuiPaneDockArtSetting. + */ + virtual int GetMetric(int id); + + /** + The same as SetColour(). + */ + virtual void SetColor(int id, const wxColour& color); + + /** + Set a certain setting with the value @e colour. + + @e id can be one of the colour values of @b wxAuiPaneDockArtSetting. + */ + virtual void SetColour(int id, const wxColor& colour); + + /** + Set a font setting. + */ + virtual void SetFont(int id, const wxFont& font); + + /** + Set a certain setting with the value @e new_val. + + @e id can be one of the size values of @b wxAuiPaneDockArtSetting. + */ + virtual void SetMetric(int id, int new_val); +}; diff --git a/interface/base64.h b/interface/base64.h new file mode 100644 index 0000000000..311023bf68 --- /dev/null +++ b/interface/base64.h @@ -0,0 +1,111 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: base64.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + //@{ +/** + These functions encode the given data using base64. The first of them is the + raw encoding function writing the output string into provided buffer while the + other ones return the output as wxString. There is no error return for these + functions except for the first one which returns @c wxCONV_FAILED if the + output buffer is too small. To allocate the buffer of the correct size, use + wxBase64EncodedSize or call this function with + @e dst set to @NULL -- it will then return the necessary buffer size. + + @param dst + The output buffer, may be @NULL to retrieve the needed buffer + size. + + @param dstLen + The output buffer size, ignored if dst is @NULL. + + @param src + The input buffer, must not be @NULL. + + @param srcLen + The length of the input data. +*/ +size_t wxBase64Encode(char * dst, size_t dstLen, + const void * src, + size_t srcLen); + wxString wxBase64Encode(const void * src, size_t srcLen); + wxString wxBase64Encode(const wxMemoryBuffer& buf); +//@} + + + /** + Returns the size of the buffer necessary to contain the data encoded in a + base64 string of length @e srcLen. This can be useful for allocating a + buffer to be passed to wxBase64Decode. +*/ +size_t wxBase64DecodedSize(size_t srcLen); + +/** + Returns the length of the string with base64 representation of a buffer of + specified size @e len. This can be useful for allocating the buffer passed + to wxBase64Encode. +*/ +size_t wxBase64EncodedSize(size_t len); + +//@{ +/** + These function decode a Base64-encoded string. The first version is a raw + decoding function and decodes the data into the provided buffer @e dst of + the given size @e dstLen. An error is returned if the buffer is not large + enough -- that is not at least wxBase64DecodedSize(srcLen) + bytes. The second version allocates memory internally and returns it as + wxMemoryBuffer and is recommended for normal use. + + The first version returns the number of bytes written to the buffer or the + necessary buffer size if @e dst was @NULL or @c wxCONV_FAILED on + error, e.g. if the output buffer is too small or invalid characters were + encountered in the input string. The second version returns a buffer with the + base64 decoded binary equivalent of the input string. In neither case is the + buffer NUL-terminated. + + @param dst + Pointer to output buffer, may be @NULL to just compute the + necessary buffer size. + + @param dstLen + The size of the output buffer, ignored if dst is + @NULL. + + @param src + The input string, must not be @NULL. For the version using + wxString, the input string should contain only ASCII characters. + + @param srcLen + The length of the input string or special value + wxNO_LEN if the string is NUL-terminated and the length should be + computed by this function itself. + + @param mode + This parameter specifies the function behaviour when invalid + characters are encountered in input. By default, any such character stops the + decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the white + space characters are silently skipped instead. And if it is + wxBase64DecodeMode_Relaxed, then all invalid characters are skipped. + + @param posErr + If this pointer is non-@NULL and an error occurs during + decoding, it is filled with the index of the invalid character. +*/ +size_t wxBase64Decode(void * dst, size_t dstLen, + const char * src, + size_t srcLen = wxNO_LEN, + wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, + size_t posErr = @NULL); + wxMemoryBuffer wxBase64Decode(const char * src, + size_t srcLen = wxNO_LEN, + wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, + size_t posErr = @NULL); + wxMemoryBuffer wxBase64Decode(const wxString& src, + wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, + size_t posErr = @NULL); +//@} + diff --git a/interface/bitmap.h b/interface/bitmap.h new file mode 100644 index 0000000000..64a4b1c6b8 --- /dev/null +++ b/interface/bitmap.h @@ -0,0 +1,697 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: bitmap.h +// Purpose: documentation for wxBitmapHandler class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBitmapHandler + @wxheader{bitmap.h} + + Overview + + This is the base class for implementing bitmap file loading/saving, and bitmap + creation from data. + It is used within wxBitmap and is not normally seen by the application. + + If you wish to extend the capabilities of wxBitmap, derive a class from + wxBitmapHandler + and add the handler using wxBitmap::AddHandler in your + application initialisation. + + @library{wxcore} + @category{FIXME} + + @seealso + wxBitmap, wxIcon, wxCursor +*/ +class wxBitmapHandler : public wxObject +{ +public: + /** + Default constructor. In your own default constructor, initialise the members + m_name, m_extension and m_type. + */ + wxBitmapHandler(); + + /** + Destroys the wxBitmapHandler object. + */ + ~wxBitmapHandler(); + + /** + Creates a bitmap from the given data, which can be of arbitrary type. The + wxBitmap object @e bitmap is + manipulated by this function. + + @param bitmap + The wxBitmap object. + + @param width + The width of the bitmap in pixels. + + @param height + The height of the bitmap in pixels. + + @param depth + The depth of the bitmap in pixels. If this is -1, the screen depth is used. + + @param data + Data whose type depends on the value of type. + + @param type + A bitmap type identifier - see wxBitmapHandler() for a list + of possible values. + + @returns @true if the call succeeded, @false otherwise (the default). + */ + virtual bool Create(wxBitmap* bitmap, const void* data, int type, + int width, + int height, + int depth = -1); + + /** + Gets the file extension associated with this handler. + */ + const wxString GetExtension(); + + /** + Gets the name of this handler. + */ + const wxString GetName(); + + /** + Gets the bitmap type associated with this handler. + */ + long GetType(); + + /** + Loads a bitmap from a file or resource, putting the resulting data into @e + bitmap. + + @param bitmap + The bitmap object which is to be affected by this operation. + + @param name + Either a filename or a Windows resource name. + The meaning of name is determined by the type parameter. + + @param type + See wxBitmap::wxBitmap for values this can take. + + @returns @true if the operation succeeded, @false otherwise. + + @sa wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile() + */ + bool LoadFile(wxBitmap* bitmap, const wxString& name, long type); + + /** + Saves a bitmap in the named file. + + @param bitmap + The bitmap object which is to be affected by this operation. + + @param name + A filename. The meaning of name is determined by the type parameter. + + @param type + See wxBitmap::wxBitmap for values this can take. + + @param palette + An optional palette used for saving the bitmap. + + @returns @true if the operation succeeded, @false otherwise. + + @sa wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile() + */ + bool SaveFile(wxBitmap* bitmap, const wxString& name, int type, + wxPalette* palette = @NULL); + + /** + Sets the handler extension. + + @param extension + Handler extension. + */ + void SetExtension(const wxString& extension); + + /** + Sets the handler name. + + @param name + Handler name. + */ + void SetName(const wxString& name); + + /** + Sets the handler type. + + @param name + Handler type. + */ + void SetType(long type); +}; + + +/** + @class wxBitmap + @wxheader{bitmap.h} + + This class encapsulates the concept of a platform-dependent bitmap, + either monochrome or colour or colour with alpha channel support. + + @library{wxcore} + @category{gdi} + + @stdobjects + Objects: + wxNullBitmap + + @seealso + @ref overview_wxbitmapoverview "wxBitmap overview", @ref + overview_supportedbitmapformats "supported bitmap file formats", wxDC::Blit, wxIcon, wxCursor, wxBitmap, wxMemoryDC +*/ +class wxBitmap : public wxGDIObject +{ +public: + //@{ + /** + 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. + + @param bits + Specifies an array of pixel values. + + @param width + Specifies the width of the bitmap. + + @param height + Specifies the height of the bitmap. + + @param depth + Specifies the depth of the bitmap. If this is omitted, the display depth of the + screen is used. + + @param name + This can refer to a resource name under MS Windows, or a filename under MS + Windows and X. + Its meaning is determined by the type parameter. + + @param type + May be one of the following: + + + wxBITMAP_TYPE_BMP + + + Load a Windows bitmap file. + + wxBITMAP_TYPE_BMP_RESOURCE + + + Load a Windows bitmap resource from the executable. Windows only. + + wxBITMAP_TYPE_PICT_RESOURCE + + + Load a PICT image resource from the executable. Mac OS only. + + wxBITMAP_TYPE_GIF + + + Load a GIF bitmap file. + + wxBITMAP_TYPE_XBM + + + Load an X bitmap file. + + wxBITMAP_TYPE_XPM + + + Load an XPM bitmap file. + + The validity of these flags depends on the platform and wxWidgets configuration. + If all possible wxWidgets settings are used, the Windows platform supports BMP + file, BMP resource, + XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM data, + XPM file, and PNG file. + Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file. + + In addition, wxBitmap can read all formats that wxImage can, which currently + include + wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_TIF, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF, + wxBITMAP_TYPE_PCX, + and wxBITMAP_TYPE_PNM. Of course, you must have wxImage handlers loaded. + + @param img + Platform-independent wxImage object. + + @remarks 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. + + @sa LoadFile() + */ + wxBitmap(); + wxBitmap(const wxBitmap& bitmap); + wxBitmap(const void* data, int type, int width, int height, + int depth = -1); + wxBitmap(const char bits[], int width, int height, + int depth = 1); + wxBitmap(int width, int height, int depth = -1); + wxBitmap(const char* const* bits); + wxBitmap(const wxString& name, long type); + wxBitmap(const wxImage& img, int depth = -1); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + + 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. + */ + ~wxBitmap(); + + /** + Adds a handler to the end of the static list of format handlers. + + @param handler + A new bitmap format handler object. There is usually only one instance + of a given handler class in an application session. + + @sa wxBitmapHandler + */ + static void AddHandler(wxBitmapHandler* handler); + + /** + Deletes all bitmap handlers. + + This function is called by wxWidgets on exit. + */ + static void CleanUpHandlers(); + + /** + Creates an image from a platform-dependent bitmap. This preserves + mask information so that bitmaps and images can be converted back + and forth without loss in that respect. + */ + wxImage ConvertToImage(); + + /** + Creates the bitmap from an icon. + */ + bool CopyFromIcon(const wxIcon& icon); + + //@{ + /** + Creates a bitmap from the given data, which can be of arbitrary type. + + @param width + The width of the bitmap in pixels. + + @param height + The height of the bitmap in pixels. + + @param depth + The depth of the bitmap in pixels. If this is -1, the screen depth is used. + + @param data + Data whose type depends on the value of type. + + @param type + A bitmap type identifier - see wxBitmap() for a list + of possible values. + + @returns @true if the call succeeded, @false otherwise. + + @remarks The first form works on all platforms. The portability of the + second form depends on the type of data. + + @sa wxBitmap() + */ + virtual bool Create(int width, int height, int depth = -1); + virtual bool Create(const void* data, int type, int width, + int height, + int depth = -1); + //@} + + //@{ + /** + Finds the handler associated with the given bitmap type. + + @param name + The handler name. + + @param extension + The file extension, such as "bmp". + + @param bitmapType + The bitmap type, such as wxBITMAP_TYPE_BMP. + + @returns A pointer to the handler if found, @NULL otherwise. + + @sa wxBitmapHandler + */ + static wxBitmapHandler* FindHandler(const wxString& name); + static wxBitmapHandler* FindHandler(const wxString& extension, + wxBitmapType bitmapType); + static wxBitmapHandler* FindHandler(wxBitmapType bitmapType); + //@} + + /** + Gets the colour depth of the bitmap. A value of 1 indicates a + monochrome bitmap. + */ + int GetDepth(); + + /** + Returns the static list of bitmap format handlers. + + @sa wxBitmapHandler + */ + static wxList GetHandlers(); + + /** + Gets the height of the bitmap in pixels. + */ + int GetHeight(); + + /** + Gets the associated mask (if any) which may have been loaded from a file + or set for the bitmap. + + @sa SetMask(), wxMask + */ + wxMask* GetMask(); + + /** + Gets the associated palette (if any) which may have been loaded from a file + or set for the bitmap. + + @sa wxPalette + */ + wxPalette* GetPalette(); + + /** + 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. + */ + wxBitmap GetSubBitmap(const wxRect& rect); + + /** + Gets the width of the bitmap in pixels. + + @sa GetHeight() + */ + int GetWidth(); + + /** + 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. + + @sa wxBitmapHandler + */ + static void InitStandardHandlers(); + + /** + Adds a handler at the start of the static list of format handlers. + + @param handler + A new bitmap format handler object. There is usually only one instance + of a given handler class in an application session. + + @sa wxBitmapHandler + */ + static void InsertHandler(wxBitmapHandler* handler); + + /** + Returns @true if bitmap data is present. + */ +#define bool IsOk() /* implementation is private */ + + /** + Loads a bitmap from a file or resource. + + @param name + Either a filename or a Windows resource name. + The meaning of name is determined by the type parameter. + + @param type + One of the following values: + + + wxBITMAP_TYPE_BMP + + + Load a Windows bitmap file. + + wxBITMAP_TYPE_BMP_RESOURCE + + + Load a Windows bitmap resource from the executable. + + wxBITMAP_TYPE_PICT_RESOURCE + + + Load a PICT image resource from the executable. Mac OS only. + + wxBITMAP_TYPE_GIF + + + Load a GIF bitmap file. + + wxBITMAP_TYPE_XBM + + + Load an X bitmap file. + + wxBITMAP_TYPE_XPM + + + Load an XPM bitmap file. + + The validity of these flags depends on the platform and wxWidgets configuration. + + In addition, wxBitmap can read all formats that wxImage can + (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF, wxBITMAP_TYPE_PCX, + wxBITMAP_TYPE_PNM). + (Of course you must have wxImage handlers loaded.) + + @returns @true if the operation succeeded, @false otherwise. + + @remarks A palette may be associated with the bitmap if one exists + (especially for colour Windows bitmaps), and if the + code supports it. You can check if one has been + created by using the GetPalette member. + + @sa SaveFile() + */ + bool LoadFile(const wxString& name, wxBitmapType type); + + /** + Finds the handler with the given name, and removes it. The handler + is not deleted. + + @param name + The handler name. + + @returns @true if the handler was found and removed, @false otherwise. + + @sa wxBitmapHandler + */ + static bool RemoveHandler(const wxString& name); + + /** + Saves a bitmap in the named file. + + @param name + A filename. The meaning of name is determined by the type parameter. + + @param type + One of the following values: + + + wxBITMAP_TYPE_BMP + + + Save a Windows bitmap file. + + wxBITMAP_TYPE_GIF + + + Save a GIF bitmap file. + + wxBITMAP_TYPE_XBM + + + Save an X bitmap file. + + wxBITMAP_TYPE_XPM + + + Save an XPM bitmap file. + + The validity of these flags depends on the platform and wxWidgets configuration. + + In addition, wxBitmap can save all formats that wxImage can + (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG). + (Of course you must have wxImage handlers loaded.) + + @param palette + An optional palette used for saving the bitmap. + + @returns @true if the operation succeeded, @false otherwise. + + @remarks Depending on how wxWidgets has been configured, not all formats + may be available. + + @sa LoadFile() + */ + bool SaveFile(const wxString& name, wxBitmapType type, + wxPalette* palette = @NULL); + + /** + Sets the depth member (does not affect the bitmap data). + + @param depth + Bitmap depth. + */ + void SetDepth(int depth); + + /** + Sets the height member (does not affect the bitmap data). + + @param height + Bitmap height in pixels. + */ + void SetHeight(int height); + + /** + Sets the mask for this bitmap. + + @remarks The bitmap object owns the mask once this has been called. + + @sa GetMask(), wxMask + */ + void SetMask(wxMask* mask); + + /** + Sets the associated palette. (Not implemented under GTK+). + + @param palette + The palette to set. + + @sa wxPalette + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the width member (does not affect the bitmap data). + + @param width + Bitmap width in pixels. + */ + void SetWidth(int width); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + + @param bitmap + Bitmap to assign. + */ + wxBitmap operator =(const wxBitmap& bitmap); +}; + + +/** + @class wxMask + @wxheader{bitmap.h} + + This class encapsulates a monochrome mask bitmap, where the masked area is + black and + the unmasked area is white. When associated with a bitmap and drawn in a device + context, + the unmasked area of the bitmap will be drawn, and the masked area will not be + drawn. + + @library{wxcore} + @category{gdi} + + @seealso + wxBitmap, wxDC::Blit, wxMemoryDC +*/ +class wxMask : public wxObject +{ +public: + //@{ + /** + Constructs a mask from a bitmap and a palette index that indicates the + background. Not + yet implemented for GTK. + + @param bitmap + A valid bitmap. + + @param colour + A colour specifying the transparency RGB values. + + @param index + Index into a palette, specifying the transparency colour. + */ + wxMask(); + wxMask(const wxBitmap& bitmap); + wxMask(const wxBitmap& bitmap, + const wxColour& colour); + wxMask(const wxBitmap& bitmap, int index); + //@} + + /** + Destroys the wxMask object and the underlying bitmap data. + */ + ~wxMask(); + + //@{ + /** + Constructs a mask from a bitmap and a palette index that indicates the + background. Not + yet implemented for GTK. + + @param bitmap + A valid bitmap. + + @param colour + A colour specifying the transparency RGB values. + + @param index + Index into a palette, specifying the transparency colour. + */ + bool Create(const wxBitmap& bitmap); + bool Create(const wxBitmap& bitmap, const wxColour& colour); + bool Create(const wxBitmap& bitmap, int index); + //@} +}; diff --git a/interface/bmpbuttn.h b/interface/bmpbuttn.h new file mode 100644 index 0000000000..41c1132ccb --- /dev/null +++ b/interface/bmpbuttn.h @@ -0,0 +1,222 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: bmpbuttn.h +// Purpose: documentation for wxBitmapButton class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBitmapButton + @wxheader{bmpbuttn.h} + + A bitmap button is a control that contains a bitmap. + It may be placed on a @ref overview_wxdialog "dialog box" or panel, or indeed + almost any other window. + + @beginStyleTable + @style{wxBU_AUTODRAW}: + If this is specified, the button will be drawn automatically using + the label bitmap only, providing a 3D-look border. If this style is + not specified, the button will be drawn without borders and using + all provided bitmaps. WIN32 only. + @style{wxBU_LEFT}: + Left-justifies the bitmap label. WIN32 only. + @style{wxBU_TOP}: + Aligns the bitmap label to the top of the button. WIN32 only. + @style{wxBU_RIGHT}: + Right-justifies the bitmap label. WIN32 only. + @style{wxBU_BOTTOM}: + Aligns the bitmap label to the bottom of the button. WIN32 only. + @endStyleTable + + @beginEventTable + @event{EVT_BUTTON(id\, func)}: + Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is + clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{bitmapbutton.png} + + @seealso + wxButton +*/ +class wxBitmapButton : public wxButton +{ +public: + //@{ + /** + Constructor, creating and showing a button. + + @param parent + Parent window. Must not be @NULL. + + @param id + Button identifier. The value wxID_ANY indicates a default value. + + @param bitmap + Bitmap to be displayed. + + @param pos + Button position. + + @param size + Button size. If wxDefaultSize is specified then the button is sized + appropriately for the bitmap. + + @param style + Window style. See wxBitmapButton. + + @param validator + Window validator. + + @param name + Window name. + + @remarks The bitmap parameter is normally the only bitmap you need to + provide, and wxWidgets will draw the button correctly + in its different states. If you want more control, + call any of the functions + SetBitmapSelected(), + SetBitmapFocus(), + SetBitmapDisabled(). + + @sa Create(), wxValidator + */ + wxBitmapButton(); + wxBitmapButton(wxWindow* parent, wxWindowID id, + const wxBitmap& bitmap, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "button"); + //@} + + /** + Destructor, destroying the button. + */ + ~wxBitmapButton(); + + /** + Button creation function for two-step creation. For more details, see + wxBitmapButton(). + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxBitmap& bitmap, + const wxPoint& pos, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator, + const wxString& name = "button"); + + //@{ + /** + Returns the bitmap for the disabled state, may be invalid. + + @returns A reference to the disabled state bitmap. + + @sa SetBitmapDisabled() + */ + const wxBitmap GetBitmapDisabled(); + wxBitmap GetBitmapDisabled(); + //@} + + //@{ + /** + Returns the bitmap for the focused state, may be invalid. + + @returns A reference to the focused state bitmap. + + @sa SetBitmapFocus() + */ + const wxBitmap GetBitmapFocus(); + wxBitmap GetBitmapFocus(); + //@} + + //@{ + /** + Returns the bitmap used when the mouse is over the button, may be invalid. + + @sa SetBitmapHover() + */ + const wxBitmap GetBitmapHover(); + wxBitmap GetBitmapHover(); + //@} + + //@{ + /** + Returns the label bitmap (the one passed to the constructor), always valid. + + @returns A reference to the button's label bitmap. + + @sa SetBitmapLabel() + */ + const wxBitmap GetBitmapLabel(); + wxBitmap GetBitmapLabel(); + //@} + + /** + Returns the bitmap for the selected state. + + @returns A reference to the selected state bitmap. + + @sa SetBitmapSelected() + */ + wxBitmap GetBitmapSelected(); + + /** + Sets the bitmap for the disabled button appearance. + + @param bitmap + The bitmap to set. + + @sa GetBitmapDisabled(), SetBitmapLabel(), + SetBitmapSelected(), SetBitmapFocus() + */ + void SetBitmapDisabled(const wxBitmap& bitmap); + + /** + Sets the bitmap for the button appearance when it has the keyboard focus. + + @param bitmap + The bitmap to set. + + @sa GetBitmapFocus(), SetBitmapLabel(), + SetBitmapSelected(), SetBitmapDisabled() + */ + void SetBitmapFocus(const wxBitmap& bitmap); + + /** + Sets the bitmap to be shown when the mouse is over the button. + + This function is new since wxWidgets version 2.7.0 and the hover bitmap is + currently only supported in wxMSW. + + @sa GetBitmapHover() + */ + void SetBitmapHover(const wxBitmap& bitmap); + + /** + Sets the bitmap label for the button. + + @param bitmap + The bitmap label to set. + + @remarks This is the bitmap used for the unselected state, and for all + other states if no other bitmaps are provided. + + @sa GetBitmapLabel() + */ + void SetBitmapLabel(const wxBitmap& bitmap); + + /** + Sets the bitmap for the selected (depressed) button appearance. + + @param bitmap + The bitmap to set. + */ + void SetBitmapSelected(const wxBitmap& bitmap); +}; diff --git a/interface/bmpcbox.h b/interface/bmpcbox.h new file mode 100644 index 0000000000..53d53d07d5 --- /dev/null +++ b/interface/bmpcbox.h @@ -0,0 +1,181 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: bmpcbox.h +// Purpose: documentation for wxBitmapComboBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBitmapComboBox + @wxheader{bmpcbox.h} + + A combobox that displays bitmap in front of the list items. + It currently only allows using bitmaps of one size, and resizes itself + so that a bitmap can be shown next to the text field. + + @beginStyleTable + @style{wxCB_READONLY}: + Creates a combobox without a text editor. On some platforms the + control may appear very different when this style is used. + @style{wxCB_SORT}: + Sorts the entries in the list alphabetically. + @style{wxTE_PROCESS_ENTER}: + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). Windows + only. + @endStyleTable + + @beginEventTable + @event{EVT_COMBOBOX(id\, func)}: + Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on + the list is selected. + @event{EVT_TEXT(id\, func)}: + Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text + changes. + @event{EVT_TEXT_ENTER(id\, func)}: + Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in + the combobox. + @endEventTable + + @library{wxadv} + @category{ctrl} + @appearance{bitmapcombobox.png} + + @seealso + wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxCommandEvent +*/ +class wxBitmapComboBox : public wxComboBox +{ +public: + //@{ + /** + Constructor, creating and showing a combobox. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param value + Initial selection string. An empty string indicates no selection. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param n + Number of strings with which to initialise the control. + + @param choices + An array of strings with which to initialise the control. + + @param style + Window style. See wxBitmapComboBox. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxBitmapComboBox(); + wxBitmapComboBox(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = @NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + wxBitmapComboBox(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Destructor, destroying the combobox. + */ + ~wxBitmapComboBox(); + + //@{ + /** + Adds the item to the end of the combo box, associating the given, typed or + untyped, client data pointer with the item. + */ + int Append(const wxString& item, + const wxBitmap& bitmap = wxNullBitmap); + int Append(const wxString& item, const wxBitmap& bitmap, + void * clientData); + int Append(const wxString& item, const wxBitmap& bitmap, + wxClientData * clientData); + //@} + + //@{ + /** + Creates the combobox for two-step construction. Derived classes + should call or replace this function. See wxBitmapComboBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Returns size of bitmaps used in the list. + */ + wxSize GetBitmapSize(); + + /** + Returns the bitmap of the item with the given index. + */ + wxBitmap GetItemBitmap(unsigned int n); + + //@{ + /** + Inserts the item into the list before pos, associating the given, typed or + untyped, client data pointer with the item. + Not valid for @c wxCB_SORT style, use Append instead. + */ + int Insert(const wxString& item, const wxBitmap& bitmap, + unsigned int pos); + int Insert(const wxString& item, const wxBitmap& bitmap, + unsigned int pos, + void * clientData); + int Insert(const wxString& item, const wxBitmap& bitmap, + unsigned int pos, + wxClientData * clientData); + //@} + + /** + Sets the bitmap for the given item. + */ + void SetItemBitmap(unsigned int n, const wxBitmap& bitmap); +}; diff --git a/interface/brush.h b/interface/brush.h new file mode 100644 index 0000000000..375a4f4ff1 --- /dev/null +++ b/interface/brush.h @@ -0,0 +1,333 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: brush.h +// Purpose: documentation for wxBrush class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBrush + @wxheader{brush.h} + + A brush is a drawing tool for filling in areas. It is used for painting + the background of rectangles, ellipses, etc. It has a colour and a + style. + + @library{wxcore} + @category{gdi} + + @stdobjects + 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 + + @seealso + wxBrushList, wxDC, wxDC::SetBrush +*/ +class wxBrush : public wxGDIObject +{ +public: + //@{ + /** + Copy constructor, uses @ref overview_trefcount "reference counting". + + @param colour + Colour object. + + @param colourName + Colour name. The name will be looked up in the colour database. + + @param style + One of: + + wxTRANSPARENT + + + Transparent (no fill). + + wxSOLID + + + Solid. + + wxSTIPPLE + + + Uses a bitmap as a stipple. + + wxBDIAGONAL_HATCH + + + Backward diagonal hatch. + + wxCROSSDIAG_HATCH + + + Cross-diagonal hatch. + + wxFDIAGONAL_HATCH + + + Forward diagonal hatch. + + wxCROSS_HATCH + + + Cross hatch. + + wxHORIZONTAL_HATCH + + + Horizontal hatch. + + wxVERTICAL_HATCH + + + Vertical hatch. + + @param brush + Pointer or reference to a brush to copy. + + @param stippleBitmap + A bitmap to use for stippling. + + @remarks If a stipple brush is created, the brush style will be set to + wxSTIPPLE. + + @sa wxBrushList, wxColour, wxColourDatabase + */ + wxBrush(); + wxBrush(const wxColour& colour, int style = wxSOLID); + wxBrush(const wxString& colourName, int style); + wxBrush(const wxBitmap& stippleBitmap); + wxBrush(const wxBrush& brush); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + + @remarks Although all remaining brushes are deleted when the application + exits, the application should try to clean up all + brushes itself. This is because wxWidgets cannot know + if a pointer to the brush object is stored in an + application data structure, and there is a risk of + double deletion. + */ + ~wxBrush(); + + /** + Returns a reference to the brush colour. + + @sa SetColour() + */ + wxColour GetColour(); + + /** + Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE + style, + this bitmap may be non-@NULL but uninitialised (@ref wxBitmap::isok + wxBitmap:IsOk returns @false). + + @sa SetStipple() + */ + wxBitmap * GetStipple(); + + /** + Returns the brush style, one of: + + @b wxTRANSPARENT + + + Transparent (no fill). + + @b wxSOLID + + + Solid. + + @b wxBDIAGONAL_HATCH + + + Backward diagonal hatch. + + @b wxCROSSDIAG_HATCH + + + Cross-diagonal hatch. + + @b wxFDIAGONAL_HATCH + + + Forward diagonal hatch. + + @b wxCROSS_HATCH + + + Cross hatch. + + @b wxHORIZONTAL_HATCH + + + Horizontal hatch. + + @b wxVERTICAL_HATCH + + + Vertical hatch. + + @b wxSTIPPLE + + + Stippled using a bitmap. + + @b wxSTIPPLE_MASK_OPAQUE + + + Stippled using a bitmap's mask. + + + @sa SetStyle(), SetColour(), SetStipple() + */ + int GetStyle(); + + /** + Returns @true if the style of the brush is any of hatched fills. + + @sa GetStyle() + */ + bool IsHatch(); + + /** + 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). + */ +#define bool IsOk() /* implementation is private */ + + //@{ + /** + Sets the brush colour using red, green and blue values. + + @sa GetColour() + */ + void SetColour(wxColour& colour); + void SetColour(const wxString& colourName); + void SetColour(unsigned char red, unsigned char green, + unsigned char blue); + //@} + + /** + Sets the stipple bitmap. + + @param bitmap + The bitmap to use for stippling. + + @remarks The style will be set to wxSTIPPLE, unless the bitmap has a mask + associated to it, in which case the style will be set + to wxSTIPPLE_MASK_OPAQUE. + + @sa wxBitmap + */ + void SetStipple(const wxBitmap& bitmap); + + /** + Sets the brush style. + + @param style + One of: + + wxTRANSPARENT + + + Transparent (no fill). + + wxSOLID + + + Solid. + + wxBDIAGONAL_HATCH + + + Backward diagonal hatch. + + wxCROSSDIAG_HATCH + + + Cross-diagonal hatch. + + wxFDIAGONAL_HATCH + + + Forward diagonal hatch. + + wxCROSS_HATCH + + + Cross hatch. + + wxHORIZONTAL_HATCH + + + Horizontal hatch. + + wxVERTICAL_HATCH + + + Vertical hatch. + + wxSTIPPLE + + + Stippled using a bitmap. + + wxSTIPPLE_MASK_OPAQUE + + + Stippled using a bitmap's mask. + + @sa GetStyle() + */ + void SetStyle(int style); + + /** + Inequality operator. + See @ref overview_refcountequality "reference-counted object comparison" for + more info. + */ + bool operator !=(const wxBrush& brush); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxBrush operator =(const wxBrush& brush); + + /** + Equality operator. + See @ref overview_refcountequality "reference-counted object comparison" for + more info. + */ + bool operator ==(const wxBrush& brush); +}; diff --git a/interface/buffer.h b/interface/buffer.h new file mode 100644 index 0000000000..428ebc63d7 --- /dev/null +++ b/interface/buffer.h @@ -0,0 +1,112 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: buffer.h +// Purpose: documentation for wxMemoryBuffer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMemoryBuffer + @wxheader{buffer.h} + + A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized + blocks + of memory. wxMemoryBuffer guarantees deletion of the memory block when the + object + is destroyed. + + @library{wxbase} + @category{FIXME} +*/ +class wxMemoryBuffer +{ +public: + //@{ + /** + Create a new buffer. + + @param size + size of new buffer. + */ + wxMemoryBuffer(const wxMemoryBuffer& src); + wxMemoryBuffer(size_t size); + //@} + + /** + Append a single byte to the buffer. + + @param data + New byte to append to the buffer. + */ + void AppendByte(char data); + + /** + Ensure that the buffer is big enough and return a pointer to the start + of the empty space in the buffer. This pointer can be used to directly + write data into the buffer, this new data will be appended to + the existing data. + + @param sizeNeeded + Amount of extra space required in the buffer for + the append operation + */ + void * GetAppendBuf(size_t sizeNeeded); + + /** + Returns the size of the buffer. + */ + size_t GetBufSize(); + + /** + Return a pointer to the data in the buffer. + */ + void* GetData(); + + /** + Returns the length of the valid data in the buffer. + */ + size_t GetDataLen(); + + /** + Ensure the buffer is big enough and return a pointer to the + buffer which can be used to directly write into the buffer + up to @e sizeNeeded bytes. + */ + void * GetWriteBuf(size_t sizeNeeded); + + /** + Ensures the buffer has at least @e size bytes available. + */ + void SetBufSize(size_t size); + + /** + Sets the length of the data stored in the buffer. Mainly useful for truncating + existing data. + + @param size + New length of the valid data in the buffer. This is + distinct from the allocated size + */ + void SetDataLen(size_t size); + + /** + Update the length after completing a direct append, which + you must have used GetAppendBuf() to initialise. + + @param sizeUsed + This is the amount of new data that has been + appended. + */ + void UngetAppendBuf(size_t sizeUsed); + + /** + Update the buffer after completing a direct write, which + you must have used GetWriteBuf() to initialise. + + @param sizeUsed + The amount of data written in to buffer + by the direct write + */ + void UngetWriteBuf(size_t sizeUsed); +}; diff --git a/interface/busyinfo.h b/interface/busyinfo.h new file mode 100644 index 0000000000..30305cc191 --- /dev/null +++ b/interface/busyinfo.h @@ -0,0 +1,73 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: busyinfo.h +// Purpose: documentation for wxBusyInfo class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBusyInfo + @wxheader{busyinfo.h} + + This class makes it easy to tell your user that the program is temporarily busy. + Just create a wxBusyInfo object on the stack, and within the current scope, + a message window will be shown. + + For example: + + @code + wxBusyInfo wait("Please wait, working..."); + + for (int i = 0; i 100000; i++) + { + DoACalculation(); + } + @endcode + + It works by creating a window in the constructor, + and deleting it in the destructor. + + You may also want to call wxTheApp-Yield() to refresh the window + periodically (in case it had been obscured by other windows, for + example) like this: + + @code + wxWindowDisabler disableAll; + + wxBusyInfo wait("Please wait, working..."); + + for (int i = 0; i 100000; i++) + { + DoACalculation(); + + if ( !(i % 1000) ) + wxTheApp-Yield(); + } + @endcode + + but take care to not cause undesirable reentrancies when doing it (see + wxApp::Yield for more details). The simplest way to do + it is to use wxWindowDisabler class as illustrated + in the above example. + + @library{wxcore} + @category{FIXME} +*/ +class wxBusyInfo +{ +public: + /** + Constructs a busy info window as child of @e parent and displays @e msg + in it. + + @b NB: If @e parent is not @NULL you must ensure that it is not + closed while the busy info is shown. + */ + wxBusyInfo(const wxString& msg, wxWindow* parent = @NULL); + + /** + Hides and closes the window containing the information text. + */ + ~wxBusyInfo(); +}; diff --git a/interface/button.h b/interface/button.h new file mode 100644 index 0000000000..44d483bda2 --- /dev/null +++ b/interface/button.h @@ -0,0 +1,150 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: button.h +// Purpose: documentation for wxButton class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxButton + @wxheader{button.h} + + A button is a control that contains a text string, + and is one of the most common elements of a GUI. It may be placed on a + @ref overview_wxdialog "dialog box" or panel, or indeed + almost any other window. + + @beginStyleTable + @style{wxBU_LEFT}: + Left-justifies the label. Windows and GTK+ only. + @style{wxBU_TOP}: + Aligns the label to the top of the button. Windows and GTK+ only. + @style{wxBU_RIGHT}: + Right-justifies the bitmap label. Windows and GTK+ only. + @style{wxBU_BOTTOM}: + Aligns the label to the bottom of the button. Windows and GTK+ only. + @style{wxBU_EXACTFIT}: + Creates the button as small as possible instead of making it of the + standard size (which is the default behaviour ). + @style{wxBORDER_NONE}: + Creates a flat button. Windows and GTK+ only. + @endStyleTable + + @beginEventTable + @event{EVT_BUTTON(id\, func)}: + Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is + clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{button.png} + + @seealso + wxBitmapButton +*/ +class wxButton : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a button. + + The preferred way to create standard buttons is to use default value of + @e label. If no label is supplied and @e id is one of standard IDs from + @ref overview_stockitems "this list", standard label will be used. In addition + to + that, the button will be decorated with stock icons under GTK+ 2. + + @param parent + Parent window. Must not be @NULL. + + @param id + Button identifier. A value of wxID_ANY indicates a default value. + + @param label + Text to be displayed on the button. + + @param pos + Button position. + + @param size + Button size. If the default size is specified then the button is sized + appropriately for the text. + + @param style + Window style. See wxButton. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxButton(); + wxButton(wxWindow* parent, wxWindowID id, + const wxString& label = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "button"); + //@} + + /** + Destructor, destroying the button. + */ + ~wxButton(); + + /** + Button creation function for two-step creation. For more details, see + wxButton(). + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator, + const wxString& name = "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. + */ + wxSize GetDefaultSize(); + + /** + Returns the string label for the button. + + @returns The button's label. + + @sa SetLabel() + */ + wxString GetLabel(); + + /** + This sets the button to be the default item for the panel or dialog + box. + + @remarks 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 wxTopLevelWindow::SetDefaultItem. + */ + void SetDefault(); + + /** + Sets the string label for the button. + + @param label + The label to set. + */ + void SetLabel(const wxString& label); +}; diff --git a/interface/calctrl.h b/interface/calctrl.h new file mode 100644 index 0000000000..e148da84ae --- /dev/null +++ b/interface/calctrl.h @@ -0,0 +1,373 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: calctrl.h +// Purpose: documentation for wxCalendarEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCalendarEvent + @wxheader{calctrl.h} + + The wxCalendarEvent class is used together with + wxCalendarCtrl. + + @library{wxadv} + @category{events} + + @seealso + wxCalendarCtrl +*/ +class wxCalendarEvent : public wxDateEvent +{ +public: + /** + Returns the week day on which the user clicked in + @c EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call + this function in other handlers. + */ + wxDateTime::WeekDay GetWeekDay(); + + /** + Sets the week day carried by the event, normally only used by the library + internally. + */ + void SetWeekDay(wxDateTime::WeekDay day); +}; + + +/** + @class wxCalendarDateAttr + @wxheader{calctrl.h} + + wxCalendarDateAttr is a custom attributes for a calendar date. The objects of + this class are used with wxCalendarCtrl. + + @library{wxadv} + @category{misc} + + @seealso + wxCalendarCtrl +*/ +class wxCalendarDateAttr +{ +public: + //@{ + /** + The constructors. + */ + wxCalendarDateAttr(); + wxCalendarDateAttr(const wxColour& colText, + const wxColour& colBack = wxNullColour, + const wxColour& colBorder = wxNullColour, + const wxFont& font = wxNullFont, + wxCalendarDateBorder border = wxCAL_BORDER_NONE); + wxCalendarDateAttr(wxCalendarDateBorder border, + const wxColour& colBorder = wxNullColour); + //@} + + /** + Returns the background colour to use for the item with this attribute. + */ + const wxColour GetBackgroundColour(); + + /** + Returns the border to use for the item with this attribute. + */ + wxCalendarDateBorder GetBorder(); + + /** + Returns the border colour to use for the item with this attribute. + */ + const wxColour GetBorderColour(); + + /** + Returns the font to use for the item with this attribute. + */ + const wxFont GetFont(); + + /** + Returns the text colour to use for the item with this attribute. + */ + const wxColour GetTextColour(); + + /** + Returns @true if this attribute specifies a non-default text background + colour. + */ + bool HasBackgroundColour(); + + /** + Returns @true if this attribute specifies a non-default (i.e. any) border. + */ + bool HasBorder(); + + /** + Returns @true if this attribute specifies a non-default border colour. + */ + bool HasBorderColour(); + + /** + Returns @true if this attribute specifies a non-default font. + */ + bool HasFont(); + + /** + Returns @true if this item has a non-default text foreground colour. + */ + bool HasTextColour(); + + /** + Returns @true if this attribute specifies that this item should be + displayed as a holiday. + */ + bool IsHoliday(); + + /** + Sets the text background colour to use. + */ + void SetBackgroundColour(const wxColour& colBack); + + /** + Sets the @ref overview_wxcalendardateattr "border kind" + */ + void SetBorder(wxCalendarDateBorder border); + + /** + Sets the border colour to use. + */ + void SetBorderColour(const wxColour& col); + + /** + Sets the font to use. + */ + void SetFont(const wxFont& font); + + /** + Display the date with this attribute as a holiday. + */ + void SetHoliday(bool holiday); + + /** + Sets the text (foreground) colour to use. + */ + void SetTextColour(const wxColour& colText); +}; + + +/** + @class wxCalendarCtrl + @wxheader{calctrl.h} + + 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 + @c EVT_CALENDAR event) by pressing @c 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 + wxCalendarCtrl::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 + wxCalendarDateAttr::SetHoliday method. + + As the attributes are specified for each day, they may change when the month + is changed, so you will often want to update them in + @c EVT_CALENDAR_MONTH event handler. + + @beginStyleTable + @style{wxCAL_SUNDAY_FIRST}: + Show Sunday as the first day in the week + @style{wxCAL_MONDAY_FIRST}: + Show Monday as the first day in the week + @style{wxCAL_SHOW_HOLIDAYS}: + Highlight holidays in the calendar + @style{wxCAL_NO_YEAR_CHANGE}: + Disable the year changing + @style{wxCAL_NO_MONTH_CHANGE}: + Disable the month (and, implicitly, the year) changing + @style{wxCAL_SHOW_SURROUNDING_WEEKS}: + Show the neighbouring weeks in the previous and next months + @style{wxCAL_SEQUENTIAL_MONTH_SELECTION}: + Use alternative, more compact, style for the month and year + selection controls. + @endStyleTable + + @library{wxadv} + @category{ctrl} + @appearance{calendarctrl.png} + + @seealso + @ref overview_samplecalendar "Calendar sample", wxCalendarDateAttr, + wxCalendarEvent +*/ +class wxCalendarCtrl : public wxControl +{ +public: + //@{ + /** + Does the same as Create() method. + */ + wxCalendarCtrl(); + wxCalendarCtrl(wxWindow* parent, wxWindowID id, + const wxDateTime& date = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAL_SHOW_HOLIDAYS, + const wxString& name = wxCalendarNameStr); + //@} + + /** + Destroys the control. + */ + ~wxCalendarCtrl(); + + /** + Creates the control. See @ref wxWindow::ctor wxWindow for the meaning of + the parameters and the control overview for the possible styles. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxDateTime& date = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAL_SHOW_HOLIDAYS, + const wxString& name = wxCalendarNameStr); + + /** + This function should be used instead of changing @c wxCAL_SHOW_HOLIDAYS + style bit directly. It enables or disables the special highlighting of the + holidays. + */ + void EnableHolidayDisplay(bool display = @true); + + /** + This function should be used instead of changing + @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to + change the month interactively. Note that if the month can not be changed, the + year can not be changed neither. + */ + void EnableMonthChange(bool enable = @true); + + /** + This function should be used instead of changing @c wxCAL_NO_YEAR_CHANGE + style bit directly. It allows or disallows the user to change the year + interactively. + */ + void EnableYearChange(bool enable = @true); + + /** + Returns the attribute for the given date (should be in the range 1...31). + + The returned pointer may be @NULL. + */ + wxCalendarDateAttr * GetAttr(size_t day); + + /** + Gets the currently selected date. + */ + const wxDateTime GetDate(); + + /** + Gets the background colour of the header part of the calendar window. + + @sa SetHeaderColours() + */ + const wxColour GetHeaderColourBg(); + + /** + Gets the foreground colour of the header part of the calendar window. + + @sa SetHeaderColours() + */ + const wxColour GetHeaderColourFg(); + + /** + Gets the background highlight colour. + + @sa SetHighlightColours() + */ + const wxColour GetHighlightColourBg(); + + /** + Gets the foreground highlight colour. + + @sa SetHighlightColours() + */ + const wxColour GetHighlightColourFg(); + + /** + Return the background colour currently used for holiday highlighting. + + @sa SetHolidayColours() + */ + const wxColour GetHolidayColourBg(); + + /** + Return the foreground colour currently used for holiday highlighting. + + @sa SetHolidayColours() + */ + const wxColour GetHolidayColourFg(); + + /** + Returns one of @c wxCAL_HITTEST_XXX + constants and fills either @e date or + @e wd pointer with the corresponding value depending on the hit test code. + */ + wxCalendarHitTestResult HitTest(const wxPoint& pos, + wxDateTime* date = @NULL, + wxDateTime::WeekDay* wd = @NULL); + + /** + Clears any attributes associated with the given day (in the range + 1...31). + */ + void ResetAttr(size_t day); + + /** + Associates the attribute with the specified date (in the range 1...31). + + If the pointer is @NULL, the items attribute is cleared. + */ + void SetAttr(size_t day, wxCalendarDateAttr* attr); + + /** + Sets the current date. + */ + void SetDate(const wxDateTime& date); + + /** + Set the colours used for painting the weekdays at the top of the control. + */ + void SetHeaderColours(const wxColour& colFg, + const wxColour& colBg); + + /** + Set the colours to be used for highlighting the currently selected date. + */ + void SetHighlightColours(const wxColour& colFg, + const wxColour& colBg); + + /** + Marks the specified day as being a holiday in the current month. + */ + void SetHoliday(size_t day); + + /** + Sets the colours to be used for the holidays highlighting (only used if the + window style includes @c wxCAL_SHOW_HOLIDAYS flag). + */ + void SetHolidayColours(const wxColour& colFg, + const wxColour& colBg); +}; diff --git a/interface/caret.h b/interface/caret.h new file mode 100644 index 0000000000..dd642a6ba2 --- /dev/null +++ b/interface/caret.h @@ -0,0 +1,155 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: caret.h +// Purpose: documentation for wxCaret class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCaret + @wxheader{caret.h} + + A caret is a blinking cursor showing the position where the typed text will + appear. 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. + + @library{wxcore} + @category{misc} + + @seealso + wxCaret::GetBlinkTime +*/ +class wxCaret +{ +public: + //@{ + /** + Create the caret of given (in pixels) width and height and associates it + with the given window. + */ + wxCaret(); + wxCaret(wxWindow* window, int width, int height); + wxCaret(wxWindowBase* window, const wxSize& size); + //@} + + //@{ + /** + Create the caret of given (in pixels) width and height and associates it + with the given window (same as constructor). + */ + bool Create(wxWindowBase* window, int width, int height); + bool Create(wxWindowBase* window, const wxSize& size); + //@} + + /** + Returns the blink time which is measured in milliseconds and is the time elapsed + between 2 inversions of the caret (blink time of the caret is the same + for all carets, so this functions is static). + */ + static int GetBlinkTime(); + + //@{ + /** + Get the caret position (in pixels). + + + + @b GetPosition() + + + Returns a Wx::Point + + @b GetPositionXY() + + + Returns a 2-element list + @c ( x, y ) + */ + void GetPosition(int* x, int* y); + wxPoint GetPosition(); + //@} + + //@{ + /** + Get the caret size. + + + + @b GetSize() + + + Returns a Wx::Size + + @b GetSizeWH() + + + Returns a 2-element list + @c ( width, height ) + */ + void GetSize(int* width, int* height); + wxSize GetSize(); + //@} + + /** + Get the window the caret is associated with. + */ + wxWindow* GetWindow(); + + /** + Same as wxCaret::Show(@false). + */ + void Hide(); + + /** + Returns @true if the caret was created successfully. + */ +#define bool IsOk() /* implementation is private */ + + /** + Returns @true if the caret is visible and @false if it is permanently + hidden (if it is is blinking and not shown currently but will be after the + next blink, this method still returns @true). + */ + bool IsVisible(); + + //@{ + /** + Move the caret to given position (in logical coordinates). + */ + void Move(int x, int y); + void Move(const wxPoint& pt); + //@} + + /** + Sets the blink time for all the carets. + + @remarks 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. + + @sa GetBlinkTime() + */ + static void SetBlinkTime(int milliseconds); + + //@{ + /** + Changes the size of the caret. + */ + void SetSize(int width, int height); + void SetSize(const wxSize& size); + //@} + + /** + Shows or hides the caret. Notice that if the caret was hidden N times, it + must be shown N times as well to reappear on the screen. + */ + void Show(bool show = @true); +}; diff --git a/interface/chartype.h b/interface/chartype.h new file mode 100644 index 0000000000..702e85f4e2 --- /dev/null +++ b/interface/chartype.h @@ -0,0 +1,47 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: chartype.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + //@{ +/** + wxT() is a macro which can be used with character and string literals (in other + words, @c 'x' or @c "foo") to automatically convert them to Unicode in + Unicode build configuration. Please see the + @ref overview_unicode "Unicode overview" for more information. + + This macro is simply returns the value passed to it without changes in ASCII + build. In fact, its definition is: + + @code + #ifdef UNICODE + #define wxT(x) L ## x + #else // !Unicode + #define wxT(x) x + #endif + @endcode +*/ +wxChar wxT(char ch); + const wxChar * wxT(const char * s); +//@} + + + //@{ +/** + wxS is macro which can be used with character and string literals to either + convert them to wide characters or strings in @c wchar_t-based Unicode + builds or keep them unchanged in UTF-8 builds. The use of this macro is + optional as the translation will always be done at run-time even if there is a + mismatch between the kind of the literal used and wxStringCharType used in the + current build, but using it can be beneficial in performance-sensitive code to + do the conversion at compile-time instead. + + @sa wxT +*/ +wxStringCharType wxS(char ch); + const wxStringCharType * wxS(const char * s); +//@} + diff --git a/interface/checkbox.h b/interface/checkbox.h new file mode 100644 index 0000000000..12d212ccc3 --- /dev/null +++ b/interface/checkbox.h @@ -0,0 +1,157 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: checkbox.h +// Purpose: documentation for wxCheckBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCheckBox + @wxheader{checkbox.h} + + A checkbox is a labelled box which by default is either on (checkmark is + visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style flag + is set) it can have a third state, called the mixed or undetermined state. + Often this is used as a "Does Not Apply" state. + + @beginStyleTable + @style{wxCHK_2STATE}: + Create a 2-state checkbox. This is the default. + @style{wxCHK_3STATE}: + Create a 3-state checkbox. Not implemented in wxMGL, wxOS2 and + wxGTK built against GTK+ 1.2. + @style{wxCHK_ALLOW_3RD_STATE_FOR_USER}: + By default a user can't set a 3-state checkbox to the third state. + It can only be done from code. Using this flags allows the user to + set the checkbox to the third state by clicking. + @style{wxALIGN_RIGHT}: + Makes the text appear on the left of the checkbox. + @endStyleTable + + @beginEventTable + @event{EVT_CHECKBOX(id\, func)}: + Process a wxEVT_COMMAND_CHECKBOX_CLICKED event, when the checkbox + is clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{checkbox.png} + + @seealso + wxRadioButton, wxCommandEvent +*/ +class wxCheckBox : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a checkbox. + + @param parent + Parent window. Must not be @NULL. + + @param id + Checkbox identifier. The value wxID_ANY indicates a default value. + + @param label + Text to be displayed next to the checkbox. + + @param pos + Checkbox position. If wxDefaultPosition is specified then a default + position is chosen. + + @param size + Checkbox size. If wxDefaultSize is specified then a default size is + chosen. + + @param style + Window style. See wxCheckBox. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxCheckBox(); + wxCheckBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val, + const wxString& name = "checkBox"); + //@} + + /** + Destructor, destroying the checkbox. + */ + ~wxCheckBox(); + + /** + Creates the checkbox for two-step construction. See wxCheckBox() + for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val, + const wxString& name = "checkBox"); + + /** + Gets the state of a 3-state checkbox. + + @returns Returns wxCHK_UNCHECKED when the checkbox is unchecked, + wxCHK_CHECKED when it is checked and + wxCHK_UNDETERMINED when it's in the undetermined + state. Asserts when the function is used with a + 2-state checkbox. + */ + wxCheckBoxState Get3StateValue(); + + /** + Gets the state of a 2-state checkbox. + + @returns Returns @true if it is checked, @false otherwise. + */ + bool GetValue(); + + /** + Returns whether or not the checkbox is a 3-state checkbox. + + @returns Returns @true if this checkbox is a 3-state checkbox, @false if + it's a 2-state checkbox. + */ + bool Is3State(); + + /** + Returns whether or not the user can set the checkbox to the third state. + + @returns Returns @true if the user can set the third state of this + checkbox, @false if it can only be set + programmatically or if it's a 2-state checkbox. + */ + bool Is3rdStateAllowedForUser(); + + /** + This is just a maybe more readable synonym for + GetValue(): just as the latter, it returns + @true if the checkbox is checked and @false otherwise. + */ + bool IsChecked(); + + /** + Sets the checkbox to the given state. This does not cause a + wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted. + + @param state + If @true, the check is on, otherwise it is off. + */ + void SetValue(bool state); +}; diff --git a/interface/checklst.h b/interface/checklst.h new file mode 100644 index 0000000000..9652322fc3 --- /dev/null +++ b/interface/checklst.h @@ -0,0 +1,105 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: checklst.h +// Purpose: documentation for wxCheckListBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCheckListBox + @wxheader{checklst.h} + + 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. + + @beginEventTable + @event{EVT_CHECKLISTBOX(id\, func)}: + Process a wxEVT_COMMAND_CHECKLISTBOX_TOGGLED event, when an item in + the check list box is checked or unchecked. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{checklistbox.png} + + @seealso + wxListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent +*/ +class wxCheckListBox : public wxListBox +{ +public: + //@{ + /** + Constructor, creating and showing a list box. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param n + Number of strings with which to initialise the control. + + @param choices + An array of strings with which to initialise the control. + + @param style + Window style. See wxCheckListBox. + + @param validator + Window validator. + + @param name + Window name. + */ + wxCheckListBox(); + wxCheckListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, + const wxString choices[] = @NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + wxCheckListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + //@} + + /** + Destructor, destroying the list box. + */ + ~wxCheckListBox(); + + /** + Checks the given item. Note that calling this method doesn't result in + wxEVT_COMMAND_CHECKLISTBOX_TOGGLE being emitted. + + @param item + Index of item to check. + + @param check + @true if the item is to be checked, @false otherwise. + */ + void Check(int item, bool check = @true); +}; diff --git a/interface/choicdlg.h b/interface/choicdlg.h new file mode 100644 index 0000000000..c09dd08c1c --- /dev/null +++ b/interface/choicdlg.h @@ -0,0 +1,349 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: choicdlg.h +// Purpose: documentation for wxMultiChoiceDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMultiChoiceDialog + @wxheader{choicdlg.h} + + This class represents a dialog that shows a list of strings, and allows + the user to select one or more. + + @library{wxbase} + @category{cmndlg} + + @seealso + @ref overview_wxmultichoicedialogoverview "wxMultiChoiceDialog overview", + wxSingleChoiceDialog +*/ +class wxMultiChoiceDialog : public wxDialog +{ +public: + //@{ + /** + Constructor taking an array of wxString choices. + + @param parent + Parent window. + + @param message + Message to show on the dialog. + + @param caption + The dialog caption. + + @param n + The number of choices. + + @param choices + An array of strings, or a string list, containing the choices. + + @param style + A dialog style (bitlist) containing flags chosen from standard + dialog styles and the following: + + + wxOK + + + Show an OK button. + + wxCANCEL + + + Show a Cancel button. + + wxCENTRE + + + Centre the message. Not Windows. + + The default value is equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | + wxOK | wxCANCEL | wxCENTRE. + + @param pos + Dialog position. Not Windows. + + @remarks Use ShowModal() to show the dialog. + */ + wxMultiChoiceDialog(wxWindow* parent, const wxString& message, + const wxString& caption, + int n, + const wxString* choices, + long style = wxCHOICEDLG_STYLE, + const wxPoint& pos = wxDefaultPosition); + wxMultiChoiceDialog(wxWindow* parent, + const wxString& message, + const wxString& caption, + const wxArrayString& choices, + long style = wxCHOICEDLG_STYLE, + const wxPoint& pos = wxDefaultPosition); + //@} + + /** + Returns array with indexes of selected items. + */ + wxArrayInt GetSelection(); + + /** + Sets selected items from the array of selected items' indexes. + */ + void SetSelections(const wxArrayInt& selections); + + /** + Shows the dialog, returning either wxID_OK or wxID_CANCEL. + */ + int ShowModal(); +}; + + +/** + @class wxSingleChoiceDialog + @wxheader{choicdlg.h} + + This class represents a dialog that shows a list of strings, and allows the + user to select one. Double-clicking on a list item is equivalent to + single-clicking and then pressing OK. + + @library{wxbase} + @category{cmndlg} + + @seealso + @ref overview_wxsinglechoicedialogoverview "wxSingleChoiceDialog overview", + wxMultiChoiceDialog +*/ +class wxSingleChoiceDialog : public wxDialog +{ +public: + //@{ + /** + Constructor, taking an array of wxString choices and optional client data. + + @param parent + Parent window. + + @param message + Message to show on the dialog. + + @param caption + The dialog caption. + + @param n + The number of choices. + + @param choices + An array of strings, or a string list, containing the choices. + + @param clientData + An array of client data to be associated with the items. + See GetSelectionClientData. + + @param style + A dialog style (bitlist) containing flags chosen from standard + dialog styles and the following: + + + wxOK + + + Show an OK button. + + wxCANCEL + + + Show a Cancel button. + + wxCENTRE + + + Centre the message. Not Windows. + + The default value is equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | + wxOK | wxCANCEL | wxCENTRE. + + @param pos + Dialog position. Not Windows. + + @remarks Use ShowModal() to show the dialog. + */ + wxSingleChoiceDialog(wxWindow* parent, const wxString& message, + const wxString& caption, + int n, + const wxString* choices, + void** clientData = @NULL, + long style = wxCHOICEDLG_STYLE, + const wxPoint& pos = wxDefaultPosition); + wxSingleChoiceDialog(wxWindow* parent, + const wxString& message, + const wxString& caption, + const wxArrayString& choices, + void** clientData = @NULL, + long style = wxCHOICEDLG_STYLE, + const wxPoint& pos = wxDefaultPosition); + //@} + + /** + Returns the index of selected item. + */ + int GetSelection(); + + /** + Returns the client data associated with the selection. + */ + char* GetSelectionClientData(); + + /** + Returns the selected string. + */ + wxString GetStringSelection(); + + /** + Sets the index of the initially selected item. + */ + void SetSelection(int selection); + + /** + Shows the dialog, returning either wxID_OK or wxID_CANCEL. + */ + int ShowModal(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +//@{ +/** + As @b wxGetSingleChoice but returns the index representing the selected + string. If the user pressed cancel, -1 is returned. +*/ +int wxGetSingleChoiceIndex(const wxString& message, + const wxString& caption, + const wxArrayString& aChoices, + wxWindow * parent = @NULL, + int x = -1, + int y = -1, + bool centre = @true, + int width=150, + int height=200); + int wxGetSingleChoiceIndex(const wxString& message, + const wxString& caption, + int n, + const wxString& choices[], + wxWindow * parent = @NULL, + int x = -1, + int y = -1, + bool centre = @true, + int width=150, + int height=200); +//@} + +//@{ +/** + Pops up a dialog box containing a message, OK/Cancel buttons and a + single-selection listbox. The user may choose an item and press OK to return a + string or Cancel to return the empty string. Use + wxGetSingleChoiceIndex if empty string is a + valid choice and if you want to be able to detect pressing Cancel reliably. + + You may pass the list of strings to choose from either using @e choices + which is an array of @e n strings for the listbox or by using a single + @e aChoices parameter of type wxArrayString. + + If @e centre is @true, the message text (which may include new line + characters) is centred; if @false, the message is left-justified. +*/ +wxString wxGetSingleChoice(const wxString& message, + const wxString& caption, + const wxArrayString& aChoices, + wxWindow * parent = @NULL, + int x = -1, + int y = -1, + bool centre = @true, + int width=150, + int height=200); + wxString wxGetSingleChoice(const wxString& message, + const wxString& caption, + int n, + const wxString& choices[], + wxWindow * parent = @NULL, + int x = -1, + int y = -1, + bool centre = @true, + int width=150, + int height=200); +//@} + +//@{ +/** + As @b wxGetSingleChoice but takes an array of client data pointers + corresponding to the strings, and returns one of these pointers or @NULL if + Cancel was pressed. The @e client_data array must have the same number of + elements as @e choices or @e aChoices! +*/ +wxString wxGetSingleChoiceData(const wxString& message, + const wxString& caption, + const wxArrayString& aChoices, + const wxString& client_data[], + wxWindow * parent = @NULL, + int x = -1, + int y = -1, + bool centre = @true, + int width=150, + int height=200); + wxString wxGetSingleChoiceData(const wxString& message, + const wxString& caption, + int n, + const wxString& choices[], + const wxString& client_data[], + wxWindow * parent = @NULL, + int x = -1, + int y = -1, + bool centre = @true, + int width=150, + int height=200); +//@} + +//@{ +/** + Pops up a dialog box containing a message, OK/Cancel buttons and a + multiple-selection listbox. The user may choose an arbitrary (including 0) + number of items in the listbox whose indices will be returned in + @e selection array. The initial contents of this array will be used to + select the items when the dialog is shown. + + You may pass the list of strings to choose from either using @e choices + which is an array of @e n strings for the listbox or by using a single + @e aChoices parameter of type wxArrayString. + + If @e centre is @true, the message text (which may include new line + characters) is centred; if @false, the message is left-justified. +*/ +size_t wxGetMultipleChoices(wxArrayInt& selections, + const wxString& message, + const wxString& caption, + const wxArrayString& aChoices, + wxWindow * parent = @NULL, + int x = -1, + int y = -1, + bool centre = @true, + int width=150, + int height=200); + size_t wxGetMultipleChoices(wxArrayInt& selections, + const wxString& message, + const wxString& caption, + int n, + const wxString& choices[], + wxWindow * parent = @NULL, + int x = -1, + int y = -1, + bool centre = @true, + int width=150, + int height=200); +//@} + diff --git a/interface/choice.h b/interface/choice.h new file mode 100644 index 0000000000..491937ccc9 --- /dev/null +++ b/interface/choice.h @@ -0,0 +1,142 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: choice.h +// Purpose: documentation for wxChoice class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxChoice + @wxheader{choice.h} + + A choice item is used to select one of a list of strings. Unlike a + listbox, only the selection is visible until the user pulls down the + menu of choices. + + @beginStyleTable + @style{wxCB_SORT}: + Sorts the entries alphabetically. + @endStyleTable + + @beginEventTable + @event{EVT_CHOICE(id\, func)}: + Process a wxEVT_COMMAND_CHOICE_SELECTED event, when an item on the + list is selected. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{choice.png} + + @seealso + wxListBox, wxComboBox, wxCommandEvent +*/ +class wxChoice : public wxControlWithItems +{ +public: + //@{ + /** + Constructor, creating and showing a choice. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the choice is sized + appropriately. + + @param n + Number of strings with which to initialise the choice control. + + @param choices + An array of strings with which to initialise the choice control. + + @param style + Window style. See wxChoice. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxChoice(); + wxChoice(wxWindow * parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, int n, + const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "choice"); + wxChoice(wxWindow * parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "choice"); + //@} + + /** + Destructor, destroying the choice item. + */ + ~wxChoice(); + + //@{ + /** + Creates the choice for two-step construction. See wxChoice(). + */ + bool Create(wxWindow * parent, wxWindowID id, const wxPoint& pos, + const wxSize& size, int n, + const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "choice"); + bool Create(wxWindow * parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "choice"); + //@} + + /** + Gets the number of columns in this choice item. + + @remarks This is implemented for Motif only and always returns 1 for the + other platforms. + */ + int GetColumns(); + + /** + Unlike wxControlWithItems::GetSelection which only + returns the accepted selection value, i.e. the selection in the control once + the user closes the dropdown list, this function returns the current selection. + That is, while the dropdown list is shown, it returns the currently selected + item in it. When it is not shown, its result is the same as for the other + function. + + This function is new since wxWidgets version 2.6.2 (before this version + wxControlWithItems::GetSelection itself behaved like + this). + */ + int GetCurrentSelection(); + + /** + Sets the number of columns in this choice item. + + @param n + Number of columns. + */ + void SetColumns(int n = 1); +}; diff --git a/interface/choicebk.h b/interface/choicebk.h new file mode 100644 index 0000000000..0979d89a91 --- /dev/null +++ b/interface/choicebk.h @@ -0,0 +1,62 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: choicebk.h +// Purpose: documentation for wxChoicebook class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxChoicebook + @wxheader{choicebk.h} + + 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 @ref overview_samplenotebook "notebook sample" to see wxChoicebook in + action. + + wxChoicebook allows the use of wxBookCtrl::GetControlSizer, allowing a program + to add other controls next to the choice control. This is particularly useful + when screen space is restricted, as it often is when wxChoicebook is being + employed. + + @beginStyleTable + @style{wxCHB_DEFAULT}: + Choose the default location for the labels depending on the current + platform (left everywhere except Mac where it is top). + @style{wxCHB_TOP}: + Place labels above the page area. + @style{wxCHB_LEFT}: + Place labels on the left side. + @style{wxCHB_RIGHT}: + Place labels on the right side. + @style{wxCHB_BOTTOM}: + Place labels below the page area. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @seealso + wxBookCtrl, wxNotebook, @ref overview_samplenotebook "notebook sample" +*/ +class wxChoicebook : public wxBookCtrl overview +{ +public: + //@{ + /** + Constructs a choicebook control. + */ + wxChoicebook(); + wxChoicebook(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxEmptyStr); + //@} +}; diff --git a/interface/clipboard.h b/interface/clipboard.h new file mode 100644 index 0000000000..75f334ae75 --- /dev/null +++ b/interface/clipboard.h @@ -0,0 +1,82 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: clipboard.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + Gets the name of a registered clipboard format, and puts it into the buffer @e + formatName which is of maximum + length @e maxCount. @e dataFormat must not specify a predefined clipboard + format. +*/ +bool wxGetClipboardFormatName(int dataFormat, + const wxString& formatName, + int maxCount); + + + /** + Gets data from the clipboard. + + @e dataFormat may be one of: + + wxCF_TEXT or wxCF_OEMTEXT: returns a pointer to new memory containing a + null-terminated text string. + wxCF_BITMAP: returns a new wxBitmap. + + The clipboard must have previously been opened for this call to succeed. +*/ +wxObject * wxGetClipboardData(int dataFormat); + +/** + Returns @true if the given data format is available on the clipboard. +*/ +bool wxIsClipboardFormatAvailable(int dataFormat); + +/** + Opens the clipboard for passing data to it or getting data from it. +*/ +bool wxOpenClipboard(); + +/** + Empties the clipboard. +*/ +bool wxEmptyClipboard(); + +/** + Returns @true if this application has already opened the clipboard. +*/ +bool wxClipboardOpen(); + +/** + Registers the clipboard data format name and returns an identifier. +*/ +int wxRegisterClipboardFormat(const wxString& formatName); + +/** + Closes the clipboard to allow other applications to use it. +*/ +bool wxCloseClipboard(); + +/** + Enumerates the formats found in a list of available formats that belong + to the clipboard. Each call to this function specifies a known + available format; the function returns the format that appears next in + the list. + + @e dataFormat specifies a known format. If this parameter is zero, + the function returns the first format in the list. + + The return value specifies the next known clipboard data format if the + function is successful. It is zero if the @e dataFormat parameter specifies + the last format in the list of available formats, or if the clipboard + is not open. + + Before it enumerates the formats function, an application must open the + clipboard by using the + wxOpenClipboard function. +*/ +int wxEnumClipboardFormats(int dataFormat); + diff --git a/interface/clipbrd.h b/interface/clipbrd.h new file mode 100644 index 0000000000..1bb835a2e9 --- /dev/null +++ b/interface/clipbrd.h @@ -0,0 +1,170 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: clipbrd.h +// Purpose: documentation for wxClipboard class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxClipboard + @wxheader{clipbrd.h} + + 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 @b wxTheClipboard + object. + + See also the @ref overview_wxdataobjectoverview "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: + + @code + // Write some text to the clipboard + if (wxTheClipboard-Open()) + { + // This data objects are held by the clipboard, + // so do not delete them in the app. + wxTheClipboard-SetData( new wxTextDataObject("Some text") ); + wxTheClipboard-Close(); + } + + // Read some text + if (wxTheClipboard-Open()) + { + if (wxTheClipboard-IsSupported( wxDF_TEXT )) + { + wxTextDataObject data; + wxTheClipboard-GetData( data ); + wxMessageBox( data.GetText() ); + } + wxTheClipboard-Close(); + } + @endcode + + @library{wxcore} + @category{dnd} + + @seealso + @ref overview_wxdndoverview "Drag and drop overview", wxDataObject +*/ +class wxClipboard : public wxObject +{ +public: + /** + Constructor. + */ + wxClipboard(); + + /** + Destructor. + */ + ~wxClipboard(); + + /** + Call this function to add the data object to the clipboard. You may call + this function repeatedly after having cleared the clipboard using Clear(). + + After this function has been called, the clipboard owns the data, so do not + delete + the data explicitly. + + @sa SetData() + */ + bool AddData(wxDataObject* data); + + /** + Clears the global clipboard object and the system's clipboard if possible. + */ + void Clear(); + + /** + Call this function to close the clipboard, having opened it with Open(). + */ + void Close(); + + /** + Flushes the clipboard: this means that the data which is currently on + clipboard will stay available even after the application exits (possibly + eating memory), otherwise the clipboard will be emptied on exit. + Returns @false if the operation is unsuccessful for any reason. + */ + bool Flush(); + + /** + Call this function to fill @e data with data on the clipboard, if available in + the required + format. Returns @true on success. + */ + bool GetData(wxDataObject& data); + + /** + Returns @true if the clipboard has been opened. + */ + bool IsOpened(); + + /** + Returns @true if there is data which matches the data format of the given data + object currently @b available (IsSupported sounds like a misnomer, FIXME: better deprecate this name?) on the clipboard. + */ + bool IsSupported(const wxDataFormat& format); + + /** + Returns @true if we are using the primary selection, @false if clipboard + one. + See @ref useprimary() UsePrimarySelection for more information. + */ + bool IsUsingPrimarySelection(); + + /** + Call this function to open the clipboard before calling SetData() + and GetData(). + + Call Close() when you have finished with the clipboard. You + should keep the clipboard open for only a very short time. + + Returns @true on success. This should be tested (as in the sample shown above). + */ + bool Open(); + + /** + Call this function to set the data object to the clipboard. This function will + clear all previous contents in the clipboard, so calling it several times + does not make any sense. + + After this function has been called, the clipboard owns the data, so do not + delete + the data explicitly. + + @sa AddData() + */ + bool SetData(wxDataObject* data); + + /** + On platforms supporting it (all X11-based ports), wxClipboard uses the + CLIPBOARD X11 selection by default. When this function is called with @true + argument, all subsequent clipboard operations will use PRIMARY selection until + this function is called again with @false. + + On the other platforms, there is no PRIMARY selection and so all clipboard + operations will fail. This allows to implement the standard X11 handling of the + clipboard which consists in copying data to the CLIPBOARD selection only when + the user explicitly requests it (i.e. by selection @c "Copy" menu + command) but putting the currently selected text into the PRIMARY selection + automatically, without overwriting the normal clipboard contents with the + currently selected text on the other platforms. + */ + void UsePrimarySelection(bool primary = @true); +}; diff --git a/interface/clntdata.h b/interface/clntdata.h new file mode 100644 index 0000000000..3569cef7b1 --- /dev/null +++ b/interface/clntdata.h @@ -0,0 +1,142 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: clntdata.h +// Purpose: documentation for wxClientDataContainer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxClientDataContainer + @wxheader{clntdata.h} + + This class is a mixin that provides storage and management of "client + data." This data can either be of type void - in which case the data + @e container does not take care of freeing the data again + or it is of type wxClientData or its derivatives. In that case the + container will free the memory itself later. + Note that you @e must not assign both void data and data + derived from the wxClientData class to a container. + + NOTE: This functionality is currently duplicated in wxEvtHandler in + order to avoid having more than one vtable in that class hierarchy. + + @library{wxbase} + @category{FIXME} + + @seealso + wxEvtHandler, wxClientData +*/ +class wxClientDataContainer +{ +public: + /** + + */ + wxClientDataContainer(); + + /** + + */ + ~wxClientDataContainer(); + + /** + Get the untyped client data. + */ + void* GetClientData(); + + /** + Get a pointer to the client data object. + */ + wxClientData* GetClientObject(); + + /** + Set the untyped client data. + */ + void SetClientData(void* data); + + /** + Set the client data object. Any previous object will be deleted. + */ + void SetClientObject(wxClientData* data); +}; + + +/** + @class wxClientData + @wxheader{clntdata.h} + + All classes deriving from wxEvtHandler + (such as all controls and wxApp) + can hold arbitrary data which is here referred to as "client data". + This is useful e.g. for scripting languages which need to handle + shadow objects for most of wxWidgets' classes and which store + a handle to such a shadow class as client data in that class. + This data can either be of type void - in which case the data + @e container does not take care of freeing the data again + or it is of type wxClientData or its derivatives. In that case the + container (e.g. a control) will free the memory itself later. + Note that you @e must not assign both void data and data + derived from the wxClientData class to a container. + + Some controls can hold various items and these controls can + additionally hold client data for each item. This is the case for + wxChoice, wxComboBox + and wxListBox. wxTreeCtrl + has a specialized class wxTreeItemData + for each item in the tree. + + If you want to add client data to your own classes, you may + use the mix-in class wxClientDataContainer. + + @library{wxbase} + @category{FIXME} + + @seealso + wxEvtHandler, wxTreeItemData, wxStringClientData, wxClientDataContainer +*/ +class wxClientData +{ +public: + /** + Constructor. + */ + wxClientData(); + + /** + Virtual destructor. + */ + ~wxClientData(); +}; + + +/** + @class wxStringClientData + @wxheader{clntdata.h} + + Predefined client data class for holding a string. + + @library{wxbase} + @category{FIXME} +*/ +class wxStringClientData : public wxClientData +{ +public: + //@{ + /** + Create client data with string. + */ + wxStringClientData(); + wxStringClientData(const wxString& data); + //@} + + /** + Get string client data. + */ + const wxString GetData(); + + /** + Set string client data. + */ + void SetData(const wxString& data); +}; diff --git a/interface/clrpicker.h b/interface/clrpicker.h new file mode 100644 index 0000000000..f8dada178f --- /dev/null +++ b/interface/clrpicker.h @@ -0,0 +1,138 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: clrpicker.h +// Purpose: documentation for wxColourPickerCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxColourPickerCtrl + @wxheader{clrpicker.h} + + This control allows the user to select a colour. The generic implementation is + a button which brings up a wxColourDialog when clicked. Native implementation + may differ but this is usually a (small) widget which give access to the + colour-chooser + dialog. + It is only available if @c wxUSE_COLOURPICKERCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxCLRP_DEFAULT_STYLE}: + The default style: 0. + @style{wxCLRP_USE_TEXTCTRL}: + Creates a text control to the left of the picker button which is + completely managed by the wxColourPickerCtrl and which can be used + by the user to specify a colour (see SetColour). The text control + is automatically synchronized with button's value. Use functions + defined in wxPickerBase to modify the text control. + @style{wxCLRP_SHOW_LABEL}: + Shows the colour in HTML form (AABBCC) as colour button label + (instead of no label at all). + @endStyleTable + + @library{wxcore} + @category{miscpickers} + @appearance{colourpickerctrl.png} + + @seealso + wxColourDialog, wxColourPickerEvent +*/ +class wxColourPickerCtrl : public wxPickerBase +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxColourPickerCtrl(wxWindow * parent, wxWindowID id, + const wxColour& colour = wxBLACK, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLRP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "colourpickerctrl"); + + /** + @param parent + Parent window, must not be non-@NULL. + + @param id + The identifier for the control. + + @param colour + The initial colour shown in the control. + + @param pos + Initial position. + + @param size + Initial size. + + @param style + The window style, see wxCRLP_* flags. + + @param validator + Validator which can be used for additional date checks. + + @param name + Control name. + + @returns @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow * parent, wxWindowID id, + const wxColour& colour = wxBLACK, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLRP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "colourpickerctrl"); + + /** + Returns the currently selected colour. + */ + wxColour GetColour(); + + //@{ + /** + Sets the currently selected colour. See wxColour::Set. + */ + void SetColour(const wxColour & col); + void SetColour(const wxString & colname); + //@} +}; + + +/** + @class wxColourPickerEvent + @wxheader{clrpicker.h} + + This event class is used for the events generated by + wxColourPickerCtrl. + + @library{wxcore} + @category{FIXME} + + @seealso + wxColourPickerCtrl +*/ +class wxColourPickerEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxColourPickerEvent(wxObject * generator, int id, + const wxColour& colour); + + /** + Retrieve the colour the user has just selected. + */ + wxColour GetColour(); + + /** + Set the colour associated with the event. + */ + void SetColour(const wxColour & pos); +}; diff --git a/interface/cmdline.h b/interface/cmdline.h new file mode 100644 index 0000000000..41c83baf5e --- /dev/null +++ b/interface/cmdline.h @@ -0,0 +1,304 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cmdline.h +// Purpose: documentation for wxCmdLineParser class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCmdLineParser + @wxheader{cmdline.h} + + wxCmdLineParser is a class for parsing the command line. + + It has the following features: + + distinguishes options, switches and parameters; allows option grouping + allows both short and long options + automatically generates the usage message from the command line description + does type checks on the options values (number, date, ...). + + To use it you should follow these steps: + + @ref wxCmdLineParser::construction construct an object of this class + giving it the command line to parse and optionally its description or use + @c AddXXX() functions later + call @c Parse() + use @c Found() to retrieve the results + + 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, + @c -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, @c -o:filename might be an option which allows + to specify the name of the output file. + + + parameter + + + This is a required program argument. + + + + @library{wxbase} + @category{appmanagement} + + @seealso + wxApp::argc and wxApp::argv, console sample +*/ +class wxCmdLineParser +{ +public: + //@{ + /** + Specifies both the command line (in Windows format) and the + @ref setdesc() "command line description". + */ + wxCmdLineParser(); + wxCmdLineParser(int argc, char** argv); + wxCmdLineParser(int argc, wchar_t** argv); + wxCmdLineParser(const wxString& cmdline); + wxCmdLineParser(const wxCmdLineEntryDesc* desc); + wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, + char** argv); + wxCmdLineParser(const wxCmdLineEntryDesc* desc, + const wxString& cmdline); + //@} + + /** + Frees resources allocated by the object. + + @b NB: destructor is not virtual, don't use this class polymorphically. + */ + ~wxCmdLineParser(); + + /** + Add an option @e name with an optional long name @e lng (no long name if + it is empty, which is default) taking a value of the given type (string by + default) to the command line description. + */ + void AddOption(const wxString& name, + const wxString& lng = wxEmptyString, + const wxString& desc = wxEmptyString, + wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, + int flags = 0); + + /** + Add a parameter of the given @e type to the command line description. + */ + void AddParam(const wxString& desc = wxEmptyString, + wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, + int flags = 0); + + /** + Add a switch @e name with an optional long name @e lng (no long name if it + is empty, which is default), description @e desc and flags @e flags to the + command line description. + */ + void AddSwitch(const wxString& name, + const wxString& lng = wxEmptyString, + const wxString& desc = wxEmptyString, + int flags = 0); + + /** + Returns @true if long options are enabled, otherwise @false. + + @sa EnableLongOptions() + */ + bool AreLongOptionsEnabled(); + + /** + Before Parse() can be called, the command line + parser object must have the command line to parse and also the rules saying + which switches, options and parameters are valid - this is called command line + description in what follows. + + You have complete freedom of choice as to when specify the required information, + the only restriction is that it must be done before calling + Parse(). + + To specify the command line to parse you may use either one of constructors + accepting it (@c wxCmdLineParser(argc, argv) or @c wxCmdLineParser(const + wxString) usually) + or, if you use the default constructor, you can do it later by calling + SetCmdLine(). + + The same holds for command line description: it can be specified either in + the @ref wxcmdlineparserctor() constructor (with or without + the command line itself) or constructed later using either + SetDesc() or combination of + AddSwitch(), + AddOption() and + AddParam() methods. + + Using constructors or SetDesc() uses a (usually + @c const static) table containing the command line description. If you want + to decide which options to accept during the run-time, using one of the + @c AddXXX() functions above might be preferable. + */ + + + /** + Breaks down the string containing the full command line in words. The words are + separated by whitespace. The quotes can be used in the input string to quote + the white space and the back slashes can be used to quote the quotes. + */ + static wxArrayString ConvertStringToArgs(const wxChar cmdline); + + /** + wxCmdLineParser has several global options which may be changed by the + application. All of the functions described in this section should be called + before Parse(). + + First global option is the support for long (also known as GNU-style) options. + The long options are the ones which start with two dashes (@c "--") and look + like this: @c --verbose, i.e. they generally are complete words and not some + abbreviations of them. As long options are used by more and more applications, + they are enabled by default, but may be disabled with + DisableLongOptions(). + + Another global option is the set of characters which may be used to start an + option (otherwise, the word on the command line is assumed to be a parameter). + Under Unix, @c '-' is always used, but Windows has at least two common + choices for this: @c '-' and @c '/'. Some programs also use @c '+'. + The default is to use what suits most the current platform, but may be changed + with SetSwitchChars() method. + + Finally, SetLogo() can be used to show some + application-specific text before the explanation given by + Usage() function. + */ + + + /** + Identical to @ref enablelongoptions() EnableLongOptions(@false). + */ + void DisableLongOptions(); + + /** + Enable or disable support for the long options. + + As long options are not (yet) POSIX-compliant, this option allows to disable + them. + + @sa Customization() and AreLongOptionsEnabled() + */ + void EnableLongOptions(bool enable = @true); + + //@{ + /** + Returns @true if an option taking a date value was found and stores the + value in the provided pointer (which should not be @NULL). + */ + bool Found(const wxString& name); + bool Found(const wxString& name, wxString* value); + bool Found(const wxString& name, long* value); + bool Found(const wxString& name, wxDateTime* value); + //@} + + /** + Returns the value of Nth parameter (as string only). + */ + wxString GetParam(size_t n = 0u); + + /** + Returns the number of parameters found. This function makes sense mostly if you + had used @c wxCMD_LINE_PARAM_MULTIPLE flag. + */ + size_t GetParamCount(); + + /** + After calling Parse() (and if it returned 0), + you may access the results of parsing using one of overloaded @c Found() + methods. + + For a simple switch, you will simply call + Found() to determine if the switch was given + or not, for an option or a parameter, you will call a version of @c Found() + which also returns the associated value in the provided variable. All + @c Found() functions return @true if the switch or option were found in the + command line or @false if they were not specified. + */ + + + /** + Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help" + option was encountered and the help message was given or a positive value if a + syntax error occurred. + + @param giveUsage + If @true (default), the usage message is given if a + syntax error was encountered while parsing the command line or if help was + requested. If @false, only error messages about possible syntax errors + are given, use Usage to show the usage message + from the caller if needed. + */ + int Parse(bool giveUsage = @true); + + /** + After the command line description was constructed and the desired options were + set, you can finally call Parse() method. + It returns 0 if the command line was correct and was parsed, -1 if the help + option was specified (this is a separate case as, normally, the program will + terminate after this) or a positive number if there was an error during the + command line parsing. + + In the latter case, the appropriate error message and usage information are + logged by wxCmdLineParser itself using the standard wxWidgets logging functions. + */ + + + //@{ + /** + Set command line to parse after using one of the constructors which don't do it. + */ + void SetCmdLine(int argc, char** argv); + void SetCmdLine(int argc, wchar_t** argv); + void SetCmdLine(const wxString& cmdline); + //@} + + /** + Construct the command line description + + Take the command line description from the wxCMD_LINE_NONE terminated table. + + Example of usage: + */ + void SetDesc(const wxCmdLineEntryDesc* desc); + + /** + @e logo is some extra text which will be shown by + Usage() method. + */ + void SetLogo(const wxString& logo); + + /** + @e switchChars contains all characters with which an option or switch may + start. Default is @c "-" for Unix, @c "-/" for Windows. + */ + void SetSwitchChars(const wxString& switchChars); + + /** + Give the standard usage message describing all program options. It will use the + options and parameters descriptions specified earlier, so the resulting message + will not be helpful to the user unless the descriptions were indeed specified. + + @sa SetLogo() + */ + void Usage(); +}; diff --git a/interface/cmdproc.h b/interface/cmdproc.h new file mode 100644 index 0000000000..0234959d32 --- /dev/null +++ b/interface/cmdproc.h @@ -0,0 +1,235 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cmdproc.h +// Purpose: documentation for wxCommand class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCommand + @wxheader{cmdproc.h} + + wxCommand is a base class for modelling an application command, + which is an action usually performed by selecting a menu item, pressing + a toolbar button or any other means provided by the application to + change the data or view. + + @library{wxcore} + @category{FIXME} + + @seealso + Overview +*/ +class wxCommand : public wxObject +{ +public: + /** + Constructor. wxCommand is an abstract class, so you will need to derive + a new class and call this constructor from your own constructor. + + @e 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). + + @e name must be supplied for the command processor to display the command name + in the application's edit menu. + */ + wxCommand(bool canUndo = @false, const wxString& name = @NULL); + + /** + Destructor. + */ + ~wxCommand(); + + /** + Returns @true if the command can be undone, @false otherwise. + */ + bool CanUndo(); + + /** + Override this member function to execute the appropriate action when called. + Return @true to indicate that the action has taken place, @false otherwise. + Returning @false will indicate to the command processor that the action is + not undoable and should not be added to the command history. + */ +#define bool Do() /* implementation is private */ + + /** + Returns the command name. + */ + wxString GetName(); + + /** + 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: + + Perform an inverse operation on the last modified piece of + data in the document. When redone, a copy of data stored in command + is pasted back or some operation reapplied. This relies on the fact that + you know the ordering of Undos; the user can never Undo at an arbitrary position + in the command history. + Restore the entire document state (perhaps using document transactioning). + Potentially very inefficient, but possibly easier to code if the user interface + and data are complex, and an 'inverse execute' operation is hard to write. + + The docview sample uses the first method, to remove or restore segments + in the drawing. + */ + bool Undo(); +}; + + +/** + @class wxCommandProcessor + @wxheader{cmdproc.h} + + wxCommandProcessor is a class that maintains a history of wxCommands, + with undo/redo functionality built-in. Derive a new class from this + if you want different behaviour. + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_wxcommandprocessoroverview "wxCommandProcessor overview", + wxCommand +*/ +class wxCommandProcessor : public wxObject +{ +public: + /** + Constructor. + + @e maxCommands may be set to a positive integer to limit the number of + commands stored to it, otherwise (and by default) the list of commands can grow + arbitrarily. + */ + wxCommandProcessor(int maxCommands = -1); + + /** + Destructor. + */ + ~wxCommandProcessor(); + + /** + Returns @true if the currently-active command can be undone, @false otherwise. + */ + virtual bool CanUndo(); + + /** + Deletes all commands in the list and sets the current command pointer to @c + @NULL. + */ + virtual void ClearCommands(); + + /** + Returns the list of commands. + */ + wxList GetCommands(); + + /** + Returns the edit menu associated with the command processor. + */ + wxMenu* GetEditMenu(); + + /** + Returns the maximum number of commands that the command processor stores. + */ + int GetMaxCommands(); + + /** + Returns the string that will be appended to the Redo menu item. + */ + const wxString GetRedoAccelerator(); + + /** + Returns the string that will be shown for the redo menu item. + */ + wxString GetRedoMenuLabel(); + + /** + Returns the string that will be appended to the Undo menu item. + */ + const wxString GetUndoAccelerator(); + + /** + Returns the string that will be shown for the undo menu item. + */ + wxString GetUndoMenuLabel(); + + /** + Initializes the command processor, setting the current command to the + last in the list (if any), and updating the edit menu (if one has been + specified). + */ + virtual void Initialize(); + + /** + Returns a boolean value that indicates if changes have been made since + the last save operation. This only works if + MarkAsSaved() + is called whenever the project is saved. + */ + virtual bool IsDirty(); + + /** + You must call this method whenever the project is saved if you plan to use + IsDirty(). + */ + virtual void MarkAsSaved(); + + /** + Executes (redoes) the current command (the command that has just been undone if + any). + */ + virtual bool Redo(); + + /** + Tells the command processor to update the Undo and Redo items on this + menu as appropriate. Set this to @NULL if the menu is about to be + destroyed and command operations may still be performed, or the command + processor may try to access an invalid pointer. + */ + void SetEditMenu(wxMenu* menu); + + /** + Sets the menu labels according to the currently set menu and the current + command state. + */ + void SetMenuStrings(); + + /** + Sets the string that will be appended to the Redo menu item. + */ + void SetRedoAccelerator(const wxString& accel); + + /** + Sets the string that will be appended to the Undo menu item. + */ + void SetUndoAccelerator(const wxString& accel); + + /** + Submits a new command to the command processor. The command processor + calls wxCommand::Do to execute the command; if it succeeds, the command + is stored in the history list, and the associated edit menu (if any) updated + appropriately. If it fails, the command is deleted + immediately. Once Submit has been called, the passed command should not + be deleted directly by the application. + + @e storeIt indicates whether the successful command should be stored + in the history list. + */ + virtual bool Submit(wxCommand * command, bool storeIt = @true); + + /** + Undoes the command just executed. + */ + virtual bool Undo(); +}; diff --git a/interface/cmndata.h b/interface/cmndata.h new file mode 100644 index 0000000000..9bc6f4b10e --- /dev/null +++ b/interface/cmndata.h @@ -0,0 +1,768 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cmndata.h +// Purpose: documentation for wxFontData class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontData + @wxheader{cmndata.h} + + @ref overview_wxfontdialogoverview "wxFontDialog overview" + + This class holds a variety of information related to font dialogs. + + @library{wxcore} + @category{FIXME} + + @seealso + Overview, wxFont, wxFontDialog +*/ +class wxFontData : public wxObject +{ +public: + /** + Constructor. Initializes @e fontColour to black, @e showHelp to black, + @e allowSymbols to @true, @e enableEffects to @true, + @e minSize to 0 and @e maxSize to 0. + */ + wxFontData(); + + /** + 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. + */ + void EnableEffects(bool enable); + + /** + Under MS Windows, returns a flag determining whether symbol fonts can be + selected. Has no + effect on other platforms. + + The default value is @true. + */ + bool GetAllowSymbols(); + + /** + Gets the font chosen by the user if the user pressed OK + (wxFontDialog::ShowModal returned wxID_OK). + */ + wxFont GetChosenFont(); + + /** + Gets the colour associated with the font dialog. + + The default value is black. + */ + wxColour GetColour(); + + /** + Determines whether 'effects' are enabled under Windows. This refers to the + controls for manipulating colour, strikeout and underline properties. + + The default value is @true. + */ + bool GetEnableEffects(); + + /** + Gets the font that will be initially used by the font dialog. This should have + previously been set by the application. + */ + wxFont GetInitialFont(); + + /** + Returns @true if the Help button will be shown (Windows only). + + The default value is @false. + */ + bool GetShowHelp(); + + /** + Under MS Windows, determines whether symbol fonts can be selected. Has no + effect on other platforms. + + The default value is @true. + */ + void SetAllowSymbols(bool allowSymbols); + + /** + Sets the font that will be returned to the user (for internal use only). + */ + void SetChosenFont(const wxFont& font); + + /** + Sets the colour that will be used for the font foreground colour. + + The default colour is black. + */ + void SetColour(const wxColour& colour); + + /** + Sets the font that will be initially used by the font dialog. + */ + void SetInitialFont(const wxFont& font); + + /** + Sets the valid range for the font point size (Windows only). + + The default is 0, 0 (unrestricted range). + */ + void SetRange(int min, int max); + + /** + Determines whether the Help button will be displayed in the font dialog + (Windows only). + + The default value is @false. + */ + void SetShowHelp(bool showHelp); + + /** + Assignment operator for the font data. + */ + void operator =(const wxFontData& data); +}; + + +/** + @class wxPageSetupDialogData + @wxheader{cmndata.h} + + This class holds a variety of information related to wxPageSetupDialog. + + It contains a wxPrintData member which is used to hold basic printer + configuration data (as opposed to the + user-interface configuration settings stored by wxPageSetupDialogData). + + @library{wxcore} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", wxPageSetupDialog +*/ +class wxPageSetupDialogData : public wxObject +{ +public: + //@{ + /** + Construct an object from a print data object. + */ + wxPageSetupDialogData(); + wxPageSetupDialogData(wxPageSetupDialogData& data); + wxPageSetupDialogData(wxPrintData& printData); + //@} + + /** + Destructor. + */ + ~wxPageSetupDialogData(); + + /** + Enables or disables the 'Help' button (Windows only). + */ + void EnableHelp(bool flag); + + /** + Enables or disables the margin controls (Windows only). + */ + void EnableMargins(bool flag); + + /** + Enables or disables the orientation control (Windows only). + */ + void EnableOrientation(bool flag); + + /** + Enables or disables the paper size control (Windows only). + */ + void EnablePaper(bool flag); + + /** + Enables or disables the @b Printer button, which invokes a printer setup dialog. + */ + void EnablePrinter(bool flag); + + /** + Returns @true if the dialog will simply return default printer information (such + as orientation) + instead of showing a dialog. Windows only. + */ + bool GetDefaultInfo(); + + /** + Returns @true if the page setup dialog will take its minimum margin values from + the currently + selected printer properties. Windows only. + */ + bool GetDefaultMinMargins(); + + /** + Returns @true if the printer setup button is enabled. + */ + bool GetEnableHelp(); + + /** + Returns @true if the margin controls are enabled (Windows only). + */ + bool GetEnableMargins(); + + /** + Returns @true if the orientation control is enabled (Windows only). + */ + bool GetEnableOrientation(); + + /** + Returns @true if the paper size control is enabled (Windows only). + */ + bool GetEnablePaper(); + + /** + Returns @true if the printer setup button is enabled. + */ + bool GetEnablePrinter(); + + /** + Returns the right (x) and bottom (y) margins in millimetres. + */ + wxPoint GetMarginBottomRight(); + + /** + Returns the left (x) and top (y) margins in millimetres. + */ + wxPoint GetMarginTopLeft(); + + /** + Returns the right (x) and bottom (y) minimum margins the user can enter + (Windows only). Units + are in millimetres + */ + wxPoint GetMinMarginBottomRight(); + + /** + Returns the left (x) and top (y) minimum margins the user can enter (Windows + only). Units + are in millimetres + */ + wxPoint GetMinMarginTopLeft(); + + /** + Returns the paper id (stored in the internal wxPrintData object). + + For further information, see wxPrintData::SetPaperId. + */ + wxPaperSize GetPaperId(); + + /** + Returns the paper size in millimetres. + */ + wxSize GetPaperSize(); + + /** + Returns a reference to the @ref overview_wxprintdata "print data" associated + with this object. + */ + wxPrintData GetPrintData(); + + /** + Returns @true if the print data associated with the dialog data is valid. + This can return @false on Windows if the current printer is not set, for example. + On all other platforms, it returns @true. + */ +#define bool IsOk() /* implementation is private */ + + /** + Pass @true if the dialog will simply return default printer information (such as + orientation) + instead of showing a dialog. Windows only. + */ + void SetDefaultInfo(bool flag); + + /** + Pass @true if the page setup dialog will take its minimum margin values from the + currently + selected printer properties. Windows only. Units are in millimetres + */ + void SetDefaultMinMargins(bool flag); + + /** + Sets the right (x) and bottom (y) margins in millimetres. + */ + void SetMarginBottomRight(const wxPoint& pt); + + /** + Sets the left (x) and top (y) margins in millimetres. + */ + void SetMarginTopLeft(const wxPoint& pt); + + /** + Sets the right (x) and bottom (y) minimum margins the user can enter (Windows + only). Units are + in millimetres. + */ + void SetMinMarginBottomRight(const wxPoint& pt); + + /** + Sets the left (x) and top (y) minimum margins the user can enter (Windows + only). Units are + in millimetres. + */ + void SetMinMarginTopLeft(const wxPoint& pt); + + /** + Sets the paper size id. For further information, see wxPrintData::SetPaperId. + + Calling this function overrides the explicit paper dimensions passed in + SetPaperSize(). + */ + void SetPaperId(wxPaperSize& id); + + /** + Sets the paper size in millimetres. If a corresponding paper id is found, it + will be set in the + internal wxPrintData object, otherwise the paper size overrides the paper id. + */ + void SetPaperSize(const wxSize& size); + + /** + Sets the @ref overview_wxprintdata "print data" associated with this object. + */ + void SetPrintData(const wxPrintData& printData); + + //@{ + /** + Assigns page setup data to this object. + */ + void operator =(const wxPrintData& data); + void operator =(const wxPageSetupDialogData& data); + //@} +}; + + +/** + @class wxColourData + @wxheader{cmndata.h} + + This class holds a variety of information related to colour dialogs. + + @library{wxcore} + @category{FIXME} + + @seealso + wxColour, wxColourDialog, @ref overview_wxcolourdialogoverview "wxColourDialog + overview" +*/ +class wxColourData : public wxObject +{ +public: + /** + Constructor. Initializes the custom colours to @c wxNullColour, + the @e data colour setting + to black, and the @e choose full setting to @true. + */ + wxColourData(); + + /** + Destructor. + */ + ~wxColourData(); + + /** + Under Windows, determines whether the Windows colour dialog will display the + full dialog + with custom colour selection controls. Under PalmOS, determines whether colour + dialog + will display full rgb colour picker or only available palette indexer. + Has no meaning under other platforms. + + The default value is @true. + */ + bool GetChooseFull(); + + /** + Gets the current colour associated with the colour dialog. + + The default colour is black. + */ + wxColour GetColour(); + + /** + Gets the @e ith custom colour associated with the colour dialog. @e i should + be an integer between 0 and 15. + + The default custom colours are invalid colours. + */ + wxColour GetCustomColour(int i); + + /** + Under Windows, tells the Windows colour dialog to display the full dialog + with custom colour selection controls. Under other platforms, has no effect. + + The default value is @true. + */ + void SetChooseFull(const bool flag); + + /** + Sets the default colour for the colour dialog. + + The default colour is black. + */ + void SetColour(const wxColour& colour); + + /** + Sets the @e ith custom colour for the colour dialog. @e i should + be an integer between 0 and 15. + + The default custom colours are invalid colours. + */ + void SetCustomColour(int i, const wxColour& colour); + + /** + Assignment operator for the colour data. + */ + void operator =(const wxColourData& data); +}; + + +/** + @class wxPrintData + @wxheader{cmndata.h} + + This class holds a variety of information related to printers and + printer device contexts. This class is used to create a wxPrinterDC + and a wxPostScriptDC. It is also used as a data member of wxPrintDialogData + and wxPageSetupDialogData, as part of the mechanism for transferring data + between the print dialogs and the application. + + @library{wxcore} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", wxPrintDialog, + wxPageSetupDialog, wxPrintDialogData, wxPageSetupDialogData, @ref overview_wxprintdialogoverview "wxPrintDialog Overview", wxPrinterDC, wxPostScriptDC +*/ +class wxPrintData : public wxObject +{ +public: + //@{ + /** + Copy constructor. + */ + wxPrintData(); + wxPrintData(const wxPrintData& data); + //@} + + /** + Destructor. + */ + ~wxPrintData(); + + /** + Returns the current bin (papersource). By default, the system is left to select + the bin (@c wxPRINTBIN_DEFAULT is returned). + + See SetBin() for the full list of bin values. + */ + wxPrintBin GetBin(); + + /** + Returns @true if collation is on. + */ + bool GetCollate(); + + /** + Returns @true if colour printing is on. + */ + bool GetColour(); + + /** + Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL, + wxDUPLEX_VERTICAL. + */ + wxDuplexMode GetDuplex(); + + /** + Returns the number of copies requested by the user. + */ + int GetNoCopies(); + + /** + Gets the orientation. This can be wxLANDSCAPE or wxPORTRAIT. + */ + int GetOrientation(); + + /** + Returns the paper size id. For more information, see SetPaperId(). + */ + wxPaperSize GetPaperId(); + + /** + Returns the printer name. If the printer name is the empty string, it indicates + that the default + printer should be used. + */ + const wxString GetPrinterName(); + + /** + Returns the current print quality. This can be a positive integer, denoting the + number of dots per inch, or + one of the following identifiers: + On input you should pass one of these identifiers, but on return you may get + back a positive integer + indicating the current resolution setting. + */ + wxPrintQuality GetQuality(); + + /** + Returns @true if the print data is valid for using in print dialogs. + This can return @false on Windows if the current printer is not set, for example. + On all other platforms, it returns @true. + */ +#define bool IsOk() /* implementation is private */ + + /** + Sets the current bin. Possible values are: + */ + void SetBin(wxPrintBin flag); + + /** + Sets collation to on or off. + */ + void SetCollate(bool flag); + + /** + Sets colour printing on or off. + */ + void SetColour(bool flag); + + /** + Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL, + wxDUPLEX_VERTICAL. + */ + void SetDuplex(wxDuplexMode mode); + + /** + Sets the default number of copies to be printed out. + */ + void SetNoCopies(int n); + + /** + Sets the orientation. This can be wxLANDSCAPE or wxPORTRAIT. + */ + void SetOrientation(int orientation); + + /** + Sets the paper id. This indicates the type of paper to be used. For a mapping + between + paper id, paper size and string name, see wxPrintPaperDatabase in @c paper.h + (not yet documented). + + @e paperId can be one of: + */ + void SetPaperId(wxPaperSize paperId); + + /** + Sets the printer name. This can be the empty string to indicate that the default + printer should be used. + */ + void SetPrinterName(const wxString& printerName); + + /** + Sets the desired print quality. This can be a positive integer, denoting the + number of dots per inch, or + one of the following identifiers: + On input you should pass one of these identifiers, but on return you may get + back a positive integer + indicating the current resolution setting. + */ + void SetQuality(wxPrintQuality quality); + + //@{ + /** + Assigns print setup data to this object. wxPrintSetupData is deprecated, + but retained for backward compatibility. + */ + void operator =(const wxPrintData& data); + void operator =(const wxPrintSetupData& data); + //@} +}; + + +/** + @class wxPrintDialogData + @wxheader{cmndata.h} + + This class holds information related to the visual characteristics of + wxPrintDialog. + It contains a wxPrintData object with underlying printing settings. + + @library{wxcore} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", wxPrintDialog, + @ref overview_wxprintdialogoverview "wxPrintDialog Overview" +*/ +class wxPrintDialogData : public wxObject +{ +public: + //@{ + /** + Construct an object from a print dialog data object. + */ + wxPrintDialogData(); + wxPrintDialogData(wxPrintDialogData& dialogData); + wxPrintDialogData(wxPrintData& printData); + //@} + + /** + Destructor. + */ + ~wxPrintDialogData(); + + /** + Enables or disables the 'Help' button. + */ + void EnableHelp(bool flag); + + /** + Enables or disables the 'Page numbers' controls. + */ + void EnablePageNumbers(bool flag); + + /** + Enables or disables the 'Print to file' checkbox. + */ + void EnablePrintToFile(bool flag); + + /** + Enables or disables the 'Selection' radio button. + */ + void EnableSelection(bool flag); + + /** + Returns @true if the user requested that all pages be printed. + */ + bool GetAllPages(); + + /** + Returns @true if the user requested that the document(s) be collated. + */ + bool GetCollate(); + + /** + Returns the @e from page number, as entered by the user. + */ + int GetFromPage(); + + /** + Returns the @e maximum page number. + */ + int GetMaxPage(); + + /** + Returns the @e minimum page number. + */ + int GetMinPage(); + + /** + Returns the number of copies requested by the user. + */ + int GetNoCopies(); + + /** + Returns a reference to the internal wxPrintData object. + */ + wxPrintData GetPrintData(); + + /** + Returns @true if the user has selected printing to a file. + */ + bool GetPrintToFile(); + + /** + Returns @true if the user requested that the selection be printed (where + 'selection' is + a concept specific to the application). + */ + bool GetSelection(); + + /** + Returns the @e to page number, as entered by the user. + */ + int GetToPage(); + + /** + Returns @true if the print data is valid for using in print dialogs. + This can return @false on Windows if the current printer is not set, for example. + On all other platforms, it returns @true. + */ +#define bool IsOk() /* implementation is private */ + + /** + Sets the 'Collate' checkbox to @true or @false. + */ + void SetCollate(bool flag); + + /** + Sets the @e from page number. + */ + void SetFromPage(int page); + + /** + Sets the @e maximum page number. + */ + void SetMaxPage(int page); + + /** + Sets the @e minimum page number. + */ + void SetMinPage(int page); + + /** + Sets the default number of copies the user has requested to be printed out. + */ + void SetNoCopies(int n); + + /** + Sets the internal wxPrintData. + */ + void SetPrintData(const wxPrintData& printData); + + /** + Sets the 'Print to file' checkbox to @true or @false. + */ + void SetPrintToFile(bool flag); + + /** + Selects the 'Selection' radio button. The effect of printing the selection + depends on how the application + implements this command, if at all. + */ + void SetSelection(bool flag); + + /** + Determines whether the dialog to be shown will be the Print dialog + (pass @false) or Print Setup dialog (pass @true). + + This function has been deprecated since version 2.5.4. + */ + void SetSetupDialog(bool flag); + + /** + Sets the @e to page number. + */ + void SetToPage(int page); + + //@{ + /** + Assigns another print dialog data object to this object. + */ + void operator =(const wxPrintData& data); + void operator =(const wxPrintDialogData& data); + //@} +}; diff --git a/interface/collpane.h b/interface/collpane.h new file mode 100644 index 0000000000..332007884b --- /dev/null +++ b/interface/collpane.h @@ -0,0 +1,179 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: collpane.h +// Purpose: documentation for wxCollapsiblePaneEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCollapsiblePaneEvent + @wxheader{collpane.h} + + This event class is used for the events generated by + wxCollapsiblePane. + + @library{wxcore} + @category{FIXME} + + @seealso + wxCollapsiblePane +*/ +class wxCollapsiblePaneEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxCollapsiblePaneEvent(wxObject * generator, int id, + bool collapsed); + + /** + Returns @true if the pane has been collapsed. + */ + bool GetCollapsed(); + + /** + Sets this as a collapsed pane event (if @e collapsed is @true) or as an + expanded + pane event (if @e collapsed is @false). + */ + void SetCollapsed(bool collapsed); +}; + + +/** + @class wxCollapsiblePane + @wxheader{collpane.h} + + A collapsible pane is a container with an embedded button-like control which + can be + used by the user to collapse or expand the pane's contents. + + Once constructed you should use the wxCollapsiblePane::GetPane + function to access the pane and add your controls inside it (i.e. use the + wxCollapsiblePane::GetPane's returned pointer as parent for the + controls which must go in the pane, NOT the wxCollapsiblePane itself!). + + Note that because of its nature of control which can dynamically (and + drastically) + change its size at run-time under user-input, when putting wxCollapsiblePane + inside + a wxSizer you should be careful to add it with a proportion value + of zero; this is because otherwise all other windows with non-null proportion + values + would automatically get resized each time the user expands or collapse the pane + window + resulting usually in a weird, flickering effect. + + Usage sample: + + @code + wxCollapsiblePane *collpane = new wxCollapsiblePane(this, wxID_ANY, + wxT("Details:")); + + // add the pane with a zero proportion value to the 'sz' sizer which + contains it + sz-Add(collpane, 0, wxGROW|wxALL, 5); + + // now add a test label in the collapsible pane using a sizer to layout it: + wxWindow *win = collpane-GetPane(); + wxSizer *paneSz = new wxBoxSizer(wxVERTICAL); + paneSz-Add(new wxStaticText(win, wxID_ANY, wxT("test!")), 1, wxGROW|wxALL, + 2); + win-SetSizer(paneSz); + paneSz-SetSizeHints(win); + @endcode + + It is only available if @c wxUSE_COLLPANE is set to 1 (the default). + + @beginStyleTable + @style{wxCP_DEFAULT_STYLE}: + The default style: 0. + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{collapsiblepane.png} + + @seealso + wxPanel, wxCollapsiblePaneEvent +*/ +class wxCollapsiblePane : public wxControl +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxCollapsiblePane(wxWindow * parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "collapsiblePane"); + + /** + Collapses or expands the pane window. + */ + void Collapse(bool collapse = @true); + + /** + @param parent + Parent window, must not be non-@NULL. + + @param id + The identifier for the control. + + @param label + The initial label shown in the button which allows the user to expand or + collapse the pane window. + + @param pos + Initial position. + + @param size + Initial size. + + @param style + The window style, see wxCP_* flags. + + @param validator + Validator which can be used for additional date checks. + + @param name + Control name. + + @returns @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow * parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "collapsiblePane"); + + /** + Same as @c wxCollapsiblePane::Collapse(@false). + */ + void Expand(); + + /** + Returns a pointer to the pane window. Add controls to the returned wxWindow + to make them collapsible. + */ + wxWindow * GetPane(); + + /** + Returns @true if the pane window is currently hidden. + */ + bool IsCollapsed(); + + /** + Returns @true if the pane window is currently shown. + */ + bool IsExpanded(); +}; diff --git a/interface/colordlg.h b/interface/colordlg.h new file mode 100644 index 0000000000..cdf5cfae1e --- /dev/null +++ b/interface/colordlg.h @@ -0,0 +1,88 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: colordlg.h +// Purpose: documentation for wxColourDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxColourDialog + @wxheader{colordlg.h} + + This class represents the colour chooser dialog. + + @library{wxcore} + @category{cmndlg} + + @seealso + @ref overview_wxcolourdialogoverview "wxColourDialog Overview", wxColour, + wxColourData, wxGetColourFromUser +*/ +class wxColourDialog : public wxDialog +{ +public: + /** + Constructor. Pass a parent window, and optionally a pointer to a block of colour + data, which will be copied to the colour dialog's colour data. Custom + colours from colour data object will be be used in 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). + + @sa wxColourData + */ + wxColourDialog(wxWindow* parent, wxColourData* data = @NULL); + + /** + Destructor. + */ + ~wxColourDialog(); + + /** + Same as @ref ctor() constructor. + */ + bool Create(wxWindow* parent, wxColourData* data = @NULL); + + /** + Returns the @ref overview_wxcolourdata "colour data" associated with the colour + dialog. + */ + wxColourData GetColourData(); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL + otherwise. + */ + int ShowModal(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Shows the colour selection dialog and returns the colour selected by user or + invalid colour (use @ref wxColour::isok wxColour:IsOk to test whether a colour + is valid) if the dialog was cancelled. + + @param parent + The parent window for the colour selection dialog + + @param colInit + If given, this will be the colour initially selected in the dialog. + + @param caption + If given, this will be used for the dialog caption. + + @param data + Optional object storing additional colour dialog settings, such + as custom colours. If none is provided the same settings as the last time are + used. +*/ +wxColour wxGetColourFromUser(wxWindow * parent, + const wxColour& colInit, + const wxString& caption = wxEmptyString, + wxColourData * data = @NULL); + diff --git a/interface/colour.h b/interface/colour.h new file mode 100644 index 0000000000..dce68d54b2 --- /dev/null +++ b/interface/colour.h @@ -0,0 +1,180 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: colour.h +// Purpose: documentation for wxColour class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxColour + @wxheader{colour.h} + + A colour is an object representing a combination of Red, Green, and Blue (RGB) + intensity values, + and is used to determine drawing colours. See the + entry for wxColourDatabase for how a pointer to a predefined, + named colour may be returned instead of creating a new colour. + + Valid RGB values are in the range 0 to 255. + + You can retrieve the current system colour settings with wxSystemSettings. + + @library{wxcore} + @category{gdi} + + @stdobjects + Objects: + wxNullColour + Pointers: + wxBLACK + + wxWHITE + + wxRED + + wxBLUE + + wxGREEN + + wxCYAN + + wxLIGHT_GREY + + @seealso + wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings +*/ +class wxColour : public wxObject +{ +public: + //@{ + /** + Copy constructor. + + @param red + The red value. + + @param green + The green value. + + @param blue + The blue value. + + @param alpha + The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255 + (wxALPHA_OPAQUE). + + @param colourName + The colour name. + + @param colour + The colour to copy. + + @sa wxColourDatabase + */ + wxColour(); + wxColour(unsigned char red, unsigned char green, + unsigned char blue, + unsigned char alpha=wxALPHA_OPAQUE); + wxColour(const wxString& colourNname); + wxColour(const wxColour& colour); + //@} + + /** + Returns the alpha value, on platforms where alpha is not yet supported, this + always returns wxALPHA_OPAQUE. + */ + unsigned char Alpha(); + + /** + Returns the blue intensity. + */ + unsigned char Blue(); + + //@{ + /** + is not + specified in flags. + + This function is new since wxWidgets version 2.7.0 + */ + wxString GetAsString(long flags); + wxC2S_NAME wxC2S_CSS_SYNTAX, to obtain +the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax +(e.g. wxColour(255,0,0,85) - "rgba(255,0,0,0.333)"), and +wxC2S_HTML_SYNTAX, to obtain the colour as "#" followed +by 6 hexadecimal digits (e.g. wxColour(255,0,0) - "#FF0000"). +This function never fails and always returns a non-empty string but asserts if +the colour has alpha channel (i.e. is non opaque) but +wxC2S_CSS_SYNTAX(); + //@} + + /** + Returns a pixel value which is platform-dependent. On Windows, a COLORREF is + returned. + On X, an allocated pixel value is returned. + + -1 is returned if the pixel is invalid (on X, unallocated). + */ + long GetPixel(); + + /** + Returns the green intensity. + */ + unsigned char Green(); + + /** + Returns @true if the colour object is valid (the colour has been initialised + with RGB values). + */ +#define bool IsOk() /* implementation is private */ + + /** + Returns the red intensity. + */ +#define unsigned char Red() /* implementation is private */ + + //@{ + /** + Sets the RGB intensity values using the given values (first overload), + extracting them from the packed long (second overload), using the given string (third overloard). + + When using third form, Set() accepts: colour names (those listed in + wxTheColourDatabase), the CSS-like + @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax (case insensitive) + and the HTML-like syntax (i.e. @c "#" followed by 6 hexadecimal digits + for red, green, blue components). + + Returns @true if the conversion was successful, @false otherwise. + + This function is new since wxWidgets version 2.7.0 + */ + void Set(unsigned char red, unsigned char green, + unsigned char blue, + unsigned char alpha=wxALPHA_OPAQUE); + void Set(unsigned long RGB); + bool Set(const wxString & str); + //@} + + /** + Tests the inequality of two colours by comparing individual red, green, blue + colours and alpha values. + */ + bool operator !=(const wxColour& colour); + + //@{ + /** + Assignment operator, using a colour name to be found in the colour database. + + @sa wxColourDatabase + */ + wxColour operator =(const wxColour& colour); + wxColour operator =(const wxString& colourName); + //@} + + /** + Tests the equality of two colours by comparing individual red, green, blue + colours and alpha values. + */ + bool operator ==(const wxColour& colour); +}; diff --git a/interface/combo.h b/interface/combo.h new file mode 100644 index 0000000000..12283ab668 --- /dev/null +++ b/interface/combo.h @@ -0,0 +1,658 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: combo.h +// Purpose: documentation for wxComboPopup class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxComboPopup + @wxheader{combo.h} + + In order to use a custom popup with wxComboCtrl, + an interface class must be derived from wxComboPopup. For more information + how to use it, see @ref overview_wxcomboctrl "Setting Custom Popup for + wxComboCtrl". + + @library{wxcore} + @category{FIXME} + + @seealso + wxComboCtrl +*/ +class wxComboPopup +{ +public: + /** + Default constructor. It is recommended that internal variables + are prepared in Init() instead + (because @ref mcombo() m_combo is not valid in constructor). + */ + wxComboPopup(); + + /** + The derived class must implement this to create the popup control. + + @returns @true if the call succeeded, @false otherwise. + */ + bool Create(wxWindow* parent); + + /** + Utility function that hides the popup. + */ + void Dismiss(); + + /** + The derived class may implement this to return adjusted size + for the popup control, according to the variables given. + + @param minWidth + Preferred minimum width. + + @param prefHeight + Preferred height. May be -1 to indicate + no preference. + + @param maxWidth + Max height for window, as limited by + screen size. + + @remarks Called each time popup is about to be shown. + */ + wxSize GetAdjustedSize(int minWidth, int prefHeight, + int maxHeight); + + /** + The derived class must implement this to return pointer + to the associated control created in Create(). + */ + wxWindow* GetControl(); + + /** + The derived class must implement this to return + string representation of the value. + */ + wxString GetStringValue(); + + /** + The derived class must implement this to initialize + its internal variables. This method is called immediately + after construction finishes. @ref mcombo() m_combo + member variable has been initialized before the call. + */ + void Init(); + + /** + Utility method that returns @true if Create has been called. + + Useful in conjunction with LazyCreate(). + */ + bool IsCreated(); + + /** + The derived class may implement this to return + @true if it wants to delay call to Create() + until the popup is shown for the first time. It is more + efficient, but on the other hand it is often more convenient + to have the control created immediately. + + @remarks Base implementation returns @false. + */ + bool LazyCreate(); + + /** + The derived class may implement this to do something + when the parent wxComboCtrl gets double-clicked. + */ + void OnComboDoubleClick(); + + /** + The derived class may implement this to receive + key events from the parent wxComboCtrl. + + Events not handled should be skipped, as usual. + */ + void OnComboKeyEvent(wxKeyEvent& event); + + /** + The derived class may implement this to do + special processing when popup is hidden. + */ + void OnDismiss(); + + /** + The derived class may implement this to do + special processing when popup is shown. + */ + void OnPopup(); + + /** + The derived class may implement this to paint + the parent wxComboCtrl. + + Default implementation draws value as string. + */ + void PaintComboControl(wxDC& dc, const wxRect& rect); + + /** + The derived class must implement this to receive + string value changes from wxComboCtrl. + */ + void SetStringValue(const wxString& value); + + /** + wxComboCtrl m_combo + + Parent wxComboCtrl. This is parameter has + been prepared before Init() is called. + */ +}; + + +/** + @class wxComboCtrl + @wxheader{combo.h} + + A combo control is a generic combobox that allows totally + custom popup. In addition it has other customization features. + For instance, position and size of the dropdown button + can be changed. + + @beginStyleTable + @style{wxCB_READONLY}: + Text will not be editable. + @style{wxCB_SORT}: + Sorts the entries in the list alphabetically. + @style{wxTE_PROCESS_ENTER}: + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). Windows + only. + @style{wxCC_SPECIAL_DCLICK}: + Double-clicking triggers a call to popup's OnComboDoubleClick. + Actual behaviour is defined by a derived class. For instance, + wxOwnerDrawnComboBox will cycle an item. This style only applies if + wxCB_READONLY is used as well. + @style{wxCC_STD_BUTTON}: + Drop button will behave more like a standard push button. + @endStyleTable + + @beginEventTable + @event{EVT_TEXT(id\, func)}: + Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes. + @event{EVT_TEXT_ENTER(id\, func)}: + Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in + the combo control. + @endEventTable + + @library{wxbase} + @category{ctrl} + @appearance{comboctrl.png} + + @seealso + wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, wxCommandEvent +*/ +class wxComboCtrl : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a combo control. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param value + Initial selection string. An empty string indicates no selection. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param style + Window style. See wxComboCtrl. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxComboCtrl(); + wxComboCtrl(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboCtrl"); + //@} + + /** + Destructor, destroying the combo control. + */ + ~wxComboCtrl(); + + /** + This member function is not normally called in application code. + Instead, it can be implemented in a derived class to create a + custom popup animation. + + @returns @true if animation finishes before the function returns. @false + otherwise. In the latter case you need to manually + call DoShowPopup after the animation ends. + */ + virtual bool AnimateShow(const wxRect& rect, int flags); + + /** + Copies the selected text to the clipboard. + */ + void Copy(); + + /** + Creates the combo control for two-step construction. Derived classes + should call or replace this function. See wxComboCtrl() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboCtrl"); + + /** + Copies the selected text to the clipboard and removes the selection. + */ +#define void Cut() /* implementation is private */ + + /** + This member function is not normally called in application code. + Instead, it can be implemented in a derived class to return + default wxComboPopup, incase @c popup is @NULL. + + @b Note: If you have implemented OnButtonClick to do + something else than show the popup, then DoSetPopupControl + must always return @NULL. + */ + void DoSetPopupControl(wxComboPopup* popup); + + /** + This member function is not normally called in application code. + Instead, it must be called in a derived class to make sure popup + is properly shown after a popup animation has finished (but only + if AnimateShow() did not finish + the animation within it's function scope). + + @param rect + Position to show the popup window at, in screen coordinates. + + @param flags + Combination of any of the following: + */ + virtual void DoShowPopup(const wxRect& rect, int flags); + + /** + Enables or disables popup animation, if any, depending on the value of + the argument. + */ + void EnablePopupAnimation(bool enable = @true); + + /** + Returns disabled button bitmap that has been set with + SetButtonBitmaps(). + + @returns A reference to the disabled state bitmap. + */ + const wxBitmap GetBitmapDisabled(); + + /** + Returns button mouse hover bitmap that has been set with + SetButtonBitmaps(). + + @returns A reference to the mouse hover state bitmap. + */ + const wxBitmap GetBitmapHover(); + + /** + Returns default button bitmap that has been set with + SetButtonBitmaps(). + + @returns A reference to the normal state bitmap. + */ + const wxBitmap GetBitmapNormal(); + + /** + Returns depressed button bitmap that has been set with + SetButtonBitmaps(). + + @returns A reference to the depressed state bitmap. + */ + const wxBitmap GetBitmapPressed(); + + /** + Returns current size of the dropdown button. + */ + wxSize GetButtonSize(); + + /** + Returns custom painted area in control. + + @sa SetCustomPaintWidth(). + */ + int GetCustomPaintWidth(); + + /** + Returns features supported by wxComboCtrl. If needed feature is missing, + you need to instead use wxGenericComboCtrl, which however may lack + native look and feel (but otherwise sports identical API). + + @returns Value returned is a combination of following flags: + */ + static int GetFeatures(); + + /** + Returns the insertion point for the combo control's text field. + + @b Note: Under wxMSW, this function always returns 0 if the combo control + doesn't have the focus. + */ + long GetInsertionPoint(); + + /** + Returns the last position in the combo control text field. + */ + long GetLastPosition(); + + /** + Returns current popup interface that has been set with SetPopupControl. + */ + wxComboPopup* GetPopupControl(); + + /** + Returns popup window containing the popup control. + */ + wxWindow* GetPopupWindow(); + + /** + Get the text control which is part of the combo control. + */ + wxTextCtrl* GetTextCtrl(); + + /** + Returns actual indentation in pixels. + */ + wxCoord GetTextIndent(); + + /** + Returns area covered by the text field (includes everything except + borders and the dropdown button). + */ + const wxRect GetTextRect(); + + /** + Returns text representation of the current value. For writable + combo control it always returns the value in the text field. + */ + wxString GetValue(); + + /** + Dismisses the popup window. + */ + void HidePopup(); + + /** + Returns @true if the popup is currently shown + */ + bool IsPopupShown(); + + /** + Returns @true if the popup window is in the given state. + Possible values are: + + + @c Hidden() + + + Popup window is hidden. + + @c Animating() + + + Popup window is being shown, but the + popup animation has not yet finished. + + @c Visible() + + + Popup window is fully visible. + */ + bool IsPopupWindowState(int state); + + /** + Implement in a derived class to define what happens on + dropdown button click. + + Default action is to show the popup. + + @b Note: If you implement this to do something else than + show the popup, you must then also implement + DoSetPopupControl() to always + return @NULL. + */ + void OnButtonClick(); + + /** + Pastes text from the clipboard to the text field. + */ + void Paste(); + + /** + Removes the text between the two positions in the combo control text field. + + @param from + The first position. + + @param to + The last position. + */ + void Remove(long from, long to); + + /** + Replaces the text between two positions with the given text, in the combo + control text field. + + @param from + The first position. + + @param to + The second position. + + @param text + The text to insert. + */ + void Replace(long from, long to, const wxString& value); + + /** + Sets custom dropdown button graphics. + + @param bmpNormal + Default button image. + + @param pushButtonBg + If @true, blank push button background is painted + below the image. + + @param bmpPressed + Depressed button image. + + @param bmpHover + Button image when mouse hovers above it. This + should be ignored on platforms and themes that do not generally draw + different kind of button on mouse hover. + + @param bmpDisabled + Disabled button image. + */ + void SetButtonBitmaps(const wxBitmap& bmpNormal, + bool pushButtonBg = @false, + const wxBitmap& bmpPressed = wxNullBitmap, + const wxBitmap& bmpHover = wxNullBitmap, + const wxBitmap& bmpDisabled = wxNullBitmap); + + /** + Sets size and position of dropdown button. + + @param width + Button width. Value = 0 specifies default. + + @param height + Button height. Value = 0 specifies default. + + @param side + Indicates which side the button will be placed. + Value can be wxLEFT or wxRIGHT. + + @param spacingX + Horizontal spacing around the button. Default is 0. + */ + void SetButtonPosition(int width = -1, int height = -1, + int side = wxRIGHT, + int spacingX = 0); + + /** + Set width, in pixels, of custom painted area in control without @c wxCB_READONLY + style. In read-only wxOwnerDrawnComboBox, this is used + to indicate area that is not covered by the focus rectangle. + */ + void SetCustomPaintWidth(int width); + + /** + Sets the insertion point in the text field. + + @param pos + The new insertion point. + */ + void SetInsertionPoint(long pos); + + /** + Sets the insertion point at the end of the combo control text field. + */ + void SetInsertionPointEnd(); + + /** + Set side of the control to which the popup will align itself. Valid values are + @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that the most appropriate + side is used (which, currently, is always @c wxLEFT). + */ + void SetPopupAnchor(int anchorSide); + + /** + Set popup interface class derived from wxComboPopup. + This method should be called as soon as possible after the control + has been created, unless OnButtonClick() + has been overridden. + */ + void SetPopupControl(wxComboPopup* popup); + + /** + Extends popup size horizontally, relative to the edges of the combo control. + + @param extLeft + How many pixel to extend beyond the left edge of the + control. Default is 0. + + @param extRight + How many pixel to extend beyond the right edge of the + control. Default is 0. + + @remarks Popup minimum width may override arguments. + */ + void SetPopupExtents(int extLeft, int extRight); + + /** + Sets preferred maximum height of the popup. + + @remarks Value -1 indicates the default. + */ + void SetPopupMaxHeight(int height); + + /** + Sets minimum width of the popup. If wider than combo control, it will extend to + the left. + + @remarks Value -1 indicates the default. + */ + void SetPopupMinWidth(int width); + + /** + Selects the text between the two positions, in the combo control text field. + + @param from + The first position. + + @param to + The second position. + */ + void SetSelection(long from, long to); + + /** + Sets the text for the text field without affecting the + popup. Thus, unlike SetValue(), it works + equally well with combo control using @c wxCB_READONLY style. + */ + void SetText(const wxString& value); + + /** + This will set the space in pixels between left edge of the control and the + text, regardless whether control is read-only or not. Value -1 can be + given to indicate platform default. + */ + void SetTextIndent(int indent); + + /** + Sets the text for the combo control text field. + + @b NB: For a combo control with @c wxCB_READONLY style the + string must be accepted by the popup (for instance, exist in the dropdown + list), otherwise the call to SetValue() is ignored + */ + void SetValue(const wxString& value); + + /** + Same as SetValue, but also sends wxCommandEvent of type + wxEVT_COMMAND_TEXT_UPDATED + if @c withEvent is @true. + */ + void SetValueWithEvent(const wxString& value, + bool withEvent = @true); + + /** + Show the popup. + */ + void ShowPopup(); + + /** + Undoes the last edit in the text field. Windows only. + */ + void Undo(); + + /** + Enable or disable usage of an alternative popup window, which guarantees + ability to focus the popup control, and allows common native controls to + function normally. This alternative popup window is usually a wxDialog, + and as such, when it is shown, its parent top-level window will appear + as if the focus has been lost from it. + */ + void UseAltPopupWindow(bool enable = @true); +}; diff --git a/interface/combobox.h b/interface/combobox.h new file mode 100644 index 0000000000..5581fef469 --- /dev/null +++ b/interface/combobox.h @@ -0,0 +1,306 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: combobox.h +// Purpose: documentation for wxComboBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxComboBox + @wxheader{combobox.h} + + A combobox is like a combination of an edit control and a listbox. It can be + displayed as static list with editable or read-only text field; or a drop-down + list with + text field; or a drop-down list without a text field. + + A combobox permits a single selection only. Combobox items are numbered from + zero. + + If you need a customized combobox, have a look at wxComboCtrl, + wxOwnerDrawnComboBox, wxComboPopup + and the ready-to-use wxBitmapComboBox. + + @beginStyleTable + @style{wxCB_SIMPLE}: + Creates a combobox with a permanently displayed list. Windows only. + @style{wxCB_DROPDOWN}: + Creates a combobox with a drop-down list. + @style{wxCB_READONLY}: + Same as wxCB_DROPDOWN but only the strings specified as the + combobox choices can be selected, it is impossible to select (even + from a program) a string which is not in the choices list. + @style{wxCB_SORT}: + Sorts the entries in the list alphabetically. + @style{wxTE_PROCESS_ENTER}: + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). Windows + only. + @endStyleTable + + @beginEventTable + @event{EVT_COMBOBOX(id\, func)}: + Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on + the list is selected. Note that calling GetValue returns the new + value of selection. + @event{EVT_TEXT(id\, func)}: + Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text + changes. + @event{EVT_TEXT_ENTER(id\, func)}: + Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in + the combobox (notice that the combobox must have been created with + wxTE_PROCESS_ENTER style to receive this event). + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{combobox.png} + + @seealso + wxListBox, wxTextCtrl, wxChoice, wxCommandEvent +*/ +class wxComboBox : public wxControlWithItems +{ +public: + //@{ + /** + Constructor, creating and showing a combobox. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param value + Initial selection string. An empty string indicates no selection. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param n + Number of strings with which to initialise the control. + + @param choices + An array of strings with which to initialise the control. + + @param style + Window style. See wxComboBox. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxComboBox(); + wxComboBox(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = @NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + wxComboBox(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Destructor, destroying the combobox. + */ + ~wxComboBox(); + + /** + Returns @true if the combobox is editable and there is a text selection to copy + to the clipboard. + Only available on Windows. + */ + bool CanCopy(); + + /** + Returns @true if the combobox is editable and there is a text selection to copy + to the clipboard. + Only available on Windows. + */ + bool CanCut(); + + /** + Returns @true if the combobox is editable and there is text on the clipboard + that can be pasted into the + text field. Only available on Windows. + */ + bool CanPaste(); + + /** + Returns @true if the combobox is editable and the last undo can be redone. + Only available on Windows. + */ + bool CanRedo(); + + /** + Returns @true if the combobox is editable and the last edit can be undone. + Only available on Windows. + */ + bool CanUndo(); + + /** + Copies the selected text to the clipboard. + */ + void Copy(); + + //@{ + /** + Creates the combobox for two-step construction. Derived classes + should call or replace this function. See wxComboBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Copies the selected text to the clipboard and removes the selection. + */ +#define void Cut() /* implementation is private */ + + /** + This function does the same things as + wxChoice::GetCurrentSelection and + returns the item currently selected in the dropdown list if it's open or the + same thing as wxControlWithItems::GetSelection otherwise. + */ + int GetCurrentSelection(); + + /** + Returns the insertion point for the combobox's text field. + + @b Note: Under wxMSW, this function always returns 0 if the combobox + doesn't have the focus. + */ + long GetInsertionPoint(); + + /** + Returns the last position in the combobox text field. + */ + virtual wxTextPos GetLastPosition(); + + /** + This is the same as wxTextCtrl::GetSelection + for the text control which is part of the combobox. Notice that this is a + different method from wxControlWithItems::GetSelection. + + Currently this method is only implemented in wxMSW and wxGTK. + */ + void GetSelection(long * from, long * to); + + /** + Returns the current value in the combobox text field. + */ + wxString GetValue(); + + /** + Pastes text from the clipboard to the text field. + */ + void Paste(); + + /** + Redoes the last undo in the text field. Windows only. + */ + void Redo(); + + /** + Removes the text between the two positions in the combobox text field. + + @param from + The first position. + + @param to + The last position. + */ + void Remove(long from, long to); + + /** + Replaces the text between two positions with the given text, in the combobox + text field. + + @param from + The first position. + + @param to + The second position. + + @param text + The text to insert. + */ + void Replace(long from, long to, const wxString& text); + + /** + Sets the insertion point in the combobox text field. + + @param pos + The new insertion point. + */ + void SetInsertionPoint(long pos); + + /** + Sets the insertion point at the end of the combobox text field. + */ + void SetInsertionPointEnd(); + + /** + Selects the text between the two positions, in the combobox text field. + + @param from + The first position. + + @param to + The second position. + */ + void SetSelection(long from, long to); + + /** + Sets the text for the combobox text field. + + @b NB: For a combobox with @c wxCB_READONLY style the string must be in + the combobox choices list, otherwise the call to SetValue() is ignored. + + @param text + The text to set. + */ + void SetValue(const wxString& text); + + /** + Undoes the last edit in the text field. Windows only. + */ + void Undo(); +}; diff --git a/interface/config.h b/interface/config.h new file mode 100644 index 0000000000..cf51780a47 --- /dev/null +++ b/interface/config.h @@ -0,0 +1,606 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: config.h +// Purpose: documentation for wxConfigBase class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxConfigBase + @wxheader{config.h} + + 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 @ref overview_wxconfigoverview "config overview" for the descriptions of all + features of this class. + + It is highly recommended to use static functions @e Get() and/or @e Set(), + so please have a @ref overview_wxconfigstaticfunctions "look at them." + + @library{wxbase} + @category{misc} +*/ +class wxConfigBase : public wxObject +{ +public: + /** + ) + + This is the default and only constructor of the wxConfigBase class, and + derived classes. + + @param appName + The application name. If this is empty, the class will + normally use wxApp::GetAppName to set it. The + application name is used in the registry key on Windows, and can be used to + deduce the local filename parameter if that is missing. + + @param vendorName + The vendor name. If this is empty, it is assumed that + no vendor name is wanted, if this is optional for the current config class. + The vendor name is appended to the application name for wxRegConfig. + + @param localFilename + Some config classes require a local filename. If this + is not present, but required, the application name will be used instead. + + @param globalFilename + Some config classes require a global filename. If + this is not present, but required, the application name will be used instead. + + @param style + Can be one of wxCONFIG_USE_LOCAL_FILE and + wxCONFIG_USE_GLOBAL_FILE. The style interpretation depends on the config + class and is ignored by some implementations. For wxFileConfig, these styles + determine whether a local or global config file is created or used: if + wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the global + config file and if wxCONFIG_USE_LOCAL_FILE is used, settings are read from + and written to local config file (if they are both set, global file is read + first, then local file, overwriting global settings). If the + flag is present but the parameter is empty, the parameter will be set to a + default. If the parameter is present but the style flag not, the relevant flag + will be added to the style. For wxRegConfig, thie GLOBAL flag refers to HKLM + key while LOCAL one is for the usual HKCU one. + + For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by logically + or'ing it to either of the _FILE options to tell wxFileConfig to use relative + instead of absolute paths. + + On non-VMS Unix systems, the default local configuration file is ~/.appname. + However, this path may be also used as user data directory + (see wxStandardPaths::GetUserDataDir) if + the application has several data files. In this case wxCONFIG_USE_SUBDIR + flag, which changes the default local configuration file to ~/.appname/appname + should be used. Notice that this flag is ignored if localFilename is + provided. This function is new since wxWidgets version 2.8.2 + + For wxFileConfig, you can also add wxCONFIG_USE_NO_ESCAPE_CHARACTERS which + will turn off character escaping for the values of entries stored in the config + file: for example a foo key with some backslash characters will be stored + as foo=C:\mydir instead of the usual storage of + foo=C:\\mydir. + + The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your config + file must be read or written to by a non-wxWidgets program (which might not + understand the escape characters). Note, however, that if + wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is now + your application's responsibility to ensure that there is no newline or + other illegal characters in a value, before writing that value to the file. + + @param conv + This parameter is only used by wxFileConfig when compiled + in Unicode mode. It specifies the encoding in which the configuration file + is written. + + @remarks By default, environment variable expansion is on and recording + defaults is off. + */ + wxConfigBase(const wxString& appName = wxEmptyString, + const wxString& vendorName = wxEmptyString, + const wxString& localFilename = wxEmptyString, + const wxString& globalFilename = wxEmptyString, + long style = 0); + + /** + Empty but ensures that dtor of all derived classes is virtual. + */ + ~wxConfigBase(); + + /** + @ref ctor() wxConfigBase + + @ref dtor() ~wxConfigBase + */ + + + /** + Create a new config object: this function will create the "best" + implementation of wxConfig available for the current platform, see comments + near the definition of wxCONFIG_WIN32_NATIVE for details. It returns the + created object and also sets it as the current one. + */ + static wxConfigBase * Create(); + + /** + The functions in this section delete entries and/or groups of entries from the + config file. @e DeleteAll() is especially useful if you want to erase all + traces of your program presence: for example, when you uninstall it. + + DeleteEntry() + + DeleteGroup() + + DeleteAll() + */ + + + /** + Delete the whole underlying object (disk file, registry key, ...). Primarly + for use by uninstallation routine. + */ + bool DeleteAll(); + + /** + Deletes the specified entry and the group it belongs to if it was the last key + in it and the second parameter is @true. + */ + bool DeleteEntry(const wxString& key, + bool bDeleteGroupIfEmpty = @true); + + /** + Delete the group (with all subgroups). If the current path is under the group + being deleted it is changed to its deepest still existing component. E.g. if + the current path is @c /A/B/C/D and the group @c C is deleted the + path becomes @c /A/B. + */ + bool DeleteGroup(const wxString& key); + + /** + Calling this function will prevent @e Get() from automatically creating a + new config object if the current one is @NULL. It might be useful to call it + near the program end to prevent "accidental" creation of a new config object. + */ + void DontCreateOnDemand(); + + /** + The functions in this section allow to enumerate all entries and groups in the + config file. All functions here return @false when there are no more items. + + You must pass the same index to GetNext and GetFirst (don't modify it). + Please note that it is @b not the index of the current item (you will have + some great surprises with wxRegConfig if you assume this) and you shouldn't + even look at it: it is just a "cookie" which stores the state of the + enumeration. It can't be stored inside the class because it would prevent you + from running several enumerations simultaneously, that's why you must pass it + explicitly. + + Having said all this, enumerating the config entries/groups is very simple: + There are also functions to get the number of entries/subgroups without + actually enumerating them, but you will probably never need them. + + GetFirstGroup() + + GetNextGroup() + + GetFirstEntry() + + GetNextEntry() + + GetNumberOfEntries() + + GetNumberOfGroups() + */ + + + /** + returns @true if either a group or an entry with a given name exists + */ + bool Exists(wxString& strName); + + /** + permanently writes all changes (otherwise, they're only written from object's + destructor) + */ + bool Flush(bool bCurrentOnly = @false); + + /** + Get the current config object. If there is no current object and + @e CreateOnDemand is @true, creates one + (using @e Create) unless DontCreateOnDemand was called previously. + */ +#define static wxConfigBase * Get(bool CreateOnDemand = @true) /* implementation is private */ + + /** + Returns the application name. + */ + wxString GetAppName(); + + /** + Returns the type of the given entry or @e Unknown if the entry doesn't + exist. This function should be used to decide which version of Read() should + be used because some of wxConfig implementations will complain about type + mismatch otherwise: e.g., an attempt to read a string value from an integer + key with wxRegConfig will fail. + + The result is an element of enum EntryType: + */ + enum wxConfigBase::EntryType GetEntryType(const wxString& name); + + /** + Gets the first entry. + */ + bool GetFirstEntry(wxString& str, long& index); + + /** + Gets the first group. + */ + bool GetFirstGroup(wxString& str, long& index); + + /** + Gets the next entry. + */ + bool GetNextEntry(wxString& str, long& index); + + /** + Gets the next group. + */ + bool GetNextGroup(wxString& str, long& index); + + /** + + */ + uint GetNumberOfEntries(bool bRecursive = @false); + + /** + Get number of entries/subgroups in the current group, with or without its + subgroups. + */ + uint GetNumberOfGroups(bool bRecursive = @false); + + /** + Retrieve the current path (always as absolute path). + */ + const wxString GetPath(); + + /** + Returns the vendor name. + */ + wxString GetVendorName(); + + /** + returns @true if the entry by this name exists + */ + bool HasEntry(wxString& strName); + + /** + returns @true if the group by this name exists + */ + bool HasGroup(const wxString& strName); + + /** + Returns @true if we are expanding environment variables in key values. + */ + bool IsExpandingEnvVars(); + + /** + Returns @true if we are writing defaults back to the config file. + */ + bool IsRecordingDefaults(); + + /** + These function are the core of wxConfigBase class: they allow you to read and + write config file data. All @e Read function take a default value which + will be returned if the specified key is not found in the config file. + + Currently, supported types of data are: + wxString, @e long, @e double, @e bool, + wxColour and any other types, + for which functions wxToString + and wxFromString are defined. + + Try not to read long values into string variables and vice versa: although it + just might work with wxFileConfig, you will get a system error with + wxRegConfig because in the Windows registry the different types of entries are + indeed used. + + Final remark: the @e szKey parameter for all these functions can contain an + arbitrary path (either relative or absolute), not just the key name. + + Read() + + Write() + + Flush() + */ + + + /** + GetAppName() + + GetVendorName() + + wxFileConfig::SetUmask + */ + + + /** + Some aspects of wxConfigBase behaviour can be changed during run-time. The + first of them is the expansion of environment variables in the string values + read from the config file: for example, if you have the following in your + config file: + the call to @c config-Read("UserData") will return something like + @c "/home/zeitlin/data" if you're lucky enough to run a Linux system ;-) + + Although this feature is very useful, it may be annoying if you read a value + which containts '$' or '%' symbols (% is used for environment variables + expansion under Windows) which are not used for environment variable + expansion. In this situation you may call SetExpandEnvVars(@false) just before + reading this value and SetExpandEnvVars(@true) just after. Another solution + would be to prefix the offending symbols with a backslash. + + The following functions control this option: + + IsExpandingEnvVars() + + SetExpandEnvVars() + + SetRecordDefaults() + + IsRecordingDefaults() + */ + + + /** + As explained in @ref overview_wxconfigoverview "config overview", the config + classes + support a file system-like hierarchy of keys (files) and groups (directories). + As in the file system case, to specify a key in the config class you must use + a path to it. Config classes also support the notion of the current group, + which makes it possible to use the relative paths. To clarify all this, here + is an example (it is only for the sake of demonstration, it doesn't do anything + sensible!): + @e Warning: it is probably a good idea to always restore the path to its + old value on function exit: + because otherwise the assert in the following example will surely fail + (we suppose here that @e foo() function is the same as above except that it + doesn't save and restore the path): + Finally, the path separator in wxConfigBase and derived classes is always '/', + regardless of the platform (i.e. it is @b not '\\' under Windows). + + SetPath() + + GetPath() + */ + + + //@{ + /** + Reads a value of type T, for which function + wxFromString is defined, + returning @true if the value was found. + If the value was not found, @e defaultVal is used instead. + + bool Read(const wxStringkey, T* value) const; + + + + @b Read(key, default="") + + + Returns a string + + @b ReadInt(key, default=0) + + + Returns an integer + + @b ReadFloat(key, default=0.0) + + + Returns a floating point number + + @b ReadBool(key, default=0) + + + Returns a boolean + */ + bool Read(const wxString& key, wxString* str); + bool Read(const wxString& key, wxString* str, + const wxString& defaultVal); + wxString Read(const wxString& key, + const +wxString& defaultVal); + bool Read(const wxString& key, long* l); + bool Read(const wxString& key, long* l, long defaultVal); + bool Read(const wxString& key, double* d); + bool Read(const wxString& key, double* d, double defaultVal); + bool Read(const wxString& key, bool* b); + bool Read(const wxString& key, bool* d, bool defaultVal); + bool Read(const wxString& key, wxMemoryBuffer* buf); + bool Read(const wxString& key, T* value); + bool Read(const wxString& key, T* value, + T const& defaultVal); + //@} + + /** + Reads a bool value from the key and returns it. @e defaultVal is returned + if the key is not found. + */ + long ReadBool(const wxString& key, bool defaultVal); + + /** + Reads a double value from the key and returns it. @e defaultVal is returned + if the key is not found. + */ + long ReadDouble(const wxString& key, double defaultVal); + + /** + Reads a long value from the key and returns it. @e defaultVal is returned + if the key is not found. + */ + long ReadLong(const wxString& key, long defaultVal); + + /** + Reads a value of type T, for which function + wxFromString is defined, from the key and returns it. + @e defaultVal is returned if the key is not found. + */ + T ReadObject(const wxString& key, T const& defaultVal); + + /** + The functions in this section allow to rename entries or subgroups of the + current group. They will return @false on error. typically because either the + entry/group with the original name doesn't exist, because the entry/group with + the new name already exists or because the function is not supported in this + wxConfig implementation. + + RenameEntry() + + RenameGroup() + */ + + + /** + 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 @e oldName doesn't exist or if @e newName already + exists. + */ + bool RenameEntry(const wxString& oldName, + const wxString& newName); + + /** + Renames a subgroup of the current group. The subgroup names (both the old and + the new one) shouldn't contain backslashes, i.e. only simple names and not + arbitrary paths are accepted by this function. + + Returns @false if @e oldName doesn't exist or if @e newName already + exists. + */ + bool RenameGroup(const wxString& oldName, + const wxString& newName); + + /** + 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) + */ +#define static wxConfigBase * Set(wxConfigBase * pConfig) /* implementation is private */ + + /** + Determine whether we wish to expand environment variables in key values. + */ + void SetExpandEnvVars(bool bDoIt = @true); + + /** + 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. + */ + void SetPath(const wxString& strPath); + + /** + Sets whether defaults are recorded to the config file whenever an attempt to + read the value which is not present in it is done. + + If on (default is off) all default values for the settings used by the program + are written back to the config file. This allows the user to see what config + options may be changed and is probably useful only for wxFileConfig. + */ + void SetRecordDefaults(bool bDoIt = @true); + + /** + These functions deal with the "default" config object. Although its usage is + not at all mandatory it may be convenient to use a global config object + instead of creating and deleting the local config objects each time you need + one (especially because creating a wxFileConfig object might be a time + consuming operation). In this case, you may create this global config object + in the very start of the program and @e Set() it as the default. Then, from + anywhere in your program, you may access it using the @e Get() function. + This global wxConfig object will be deleted by wxWidgets automatically if it + exists. Note that this implies that if you do delete this object yourself + (usually in wxApp::OnExit) you must use @e Set(@NULL) + to prevent wxWidgets from deleting it the second time. + + As it happens, you may even further simplify the procedure described above: + you may forget about calling @e Set(). When @e Get() is called and there + is no current object, it will create one using @e Create() function. To + disable this behaviour @e DontCreateOnDemand() is provided. + + @b Note: You should use either @e Set() or @e Get() because wxWidgets + library itself would take advantage of it and could save various information + in it. For example wxFontMapper or Unix version + of wxFileDialog have the ability to use wxConfig class. + + Set() + + Get() + + Create() + + DontCreateOnDemand() + */ + + + /** + HasGroup() + + HasEntry() + + Exists() + + GetEntryType() + */ + + + //@{ + /** + These functions write the specified value to the config file and return @true + on success. In the last one, function wxToString must be + defined for type @e T. + + + + @b Write(key, value) + + + Writes a string + + @b WriteInt(key, value) + + + Writes an integer + + @b WriteFloat(key, value) + + + Writes a floating point number + + @b WriteBool(key, value) + + + Writes a boolean + */ + bool Write(const wxString& key, const wxString& value); + bool Write(const wxString& key, long value); + bool Write(const wxString& key, double value); + bool Write(const wxString& key, bool value); + bool Write(const wxString& key, const wxMemoryBuffer& buf); + bool Write(const wxString& key, const T& buf); + //@} +}; diff --git a/interface/control.h b/interface/control.h new file mode 100644 index 0000000000..28de175a14 --- /dev/null +++ b/interface/control.h @@ -0,0 +1,62 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: control.h +// Purpose: documentation for wxControl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxControl + @wxheader{control.h} + + This is the base class for a control or "widget''. + + A control is generally a small window which processes user input and/or + displays one or more item of data. + + @library{wxcore} + @category{ctrl} + @appearance{control.png} + + @seealso + wxValidator +*/ +class wxControl : public wxWindow +{ +public: + /** + Simulates the effect of the user issuing a command to the item. See + wxCommandEvent. + */ + void Command(wxCommandEvent& event); + + /** + Returns the control's text. + + Note that the returned string contains the mnemonics (@c characters) if + any, use GetLabelText() if they are + undesired. + */ + wxString GetLabel(); + + //@{ + /** + Returns the control's label, or the given @e label string for the static + version, without the mnemonics characters. + */ + const wxString GetLabelText(); + static wxString GetLabelText(const wxString& label); + //@} + + /** + Sets the item's text. + + The @c characters in the @e label are special and indicate that the + following character is a mnemonic for this control and can be used to activate + it from the keyboard (typically by using @e Alt key in combination with + it). To insert a literal ampersand character, you need to double it, i.e. use + @c "". + */ + void SetLabel(const wxString& label); +}; diff --git a/interface/convauto.h b/interface/convauto.h new file mode 100644 index 0000000000..fcc3427986 --- /dev/null +++ b/interface/convauto.h @@ -0,0 +1,98 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: convauto.h +// Purpose: documentation for wxConvAuto class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxConvAuto + @wxheader{convauto.h} + + This class implements a Unicode to/from multibyte converter capable of + automatically recognizing the encoding of the multibyte text on input. The + logic used is very simple: the class uses the BOM (byte order mark) if it's + present and tries to interpret the input as UTF-8 otherwise. If this fails, the + input is interpreted as being in the default multibyte encoding which can be + specified in the constructor of a wxConvAuto instance and, in turn, defaults to + the value of @ref wxConvAuto::getdefaultmbencoding GetFallbackEncoding if + not explicitly given. + + For the conversion from Unicode to multibyte, the same encoding as was + previously used for multibyte to Unicode conversion is reused. If there had + been no previous multibyte to Unicode conversion, UTF-8 is used by default. + Notice that once the multibyte encoding is automatically detected, it doesn't + change any more, i.e. it is entirely determined by the first use of wxConvAuto + object in the multibyte-to-Unicode direction. However creating a copy of + wxConvAuto object, either via the usual copy constructor or assignment + operator, or using wxMBConv::Clone method, resets the + automatically detected encoding so that the new copy will try to detect the + encoding of the input on first use. + + This class is used by default in wxWidgets classes and functions reading text + from files such as wxFile, wxFFile, + wxTextFile, wxFileConfig and + various stream classes so the encoding set with its + @ref wxConvAuto::setdefaultmbencoding SetFallbackEncoding method will + affect how these classes treat input files. In particular, use this method + to change the fall-back multibyte encoding used to interpret the contents of + the files whose contents isn't valid UTF-8 or to disallow it completely. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_mbconvclasses "wxMBConv classes overview" +*/ +class wxConvAuto : public wxMBConv +{ +public: + /** + Constructs a new wxConvAuto instance. The object will try to detect the input + of the multibyte text given to its wxMBConv::ToWChar method + automatically but if the automatic detection of Unicode encodings fails, the + fall-back encoding @e enc will be used to interpret it as multibyte text. + The default value of this parameter, @c wxFONTENCODING_DEFAULT means + that the global default value which can be set using + @ref setdefaultmbencoding() SetFallbackEncoding method should be + used. As with that method, passing @c wxFONTENCODING_MAX inhibits using + this encoding completely so the input multibyte text will always be interpreted + as UTF-8 in the absence of BOM and the conversion will fail if the input + doesn't form valid UTF-8 sequence. Another special value is + @c wxFONTENCODING_SYSTEM which means to use the encoding currently used + on the user system, i.e. the encoding returned by + wxLocale::GetSystemEncoding. Any other + encoding will be used as is, e.g. passing @c wxFONTENCODING_ISO8859_1 + ensures that non-UTF-8 input will be treated as latin1. + */ + wxConvAuto(wxFontEncoding enc = wxFONTENCODING_DEFAULT); + + /** + Disable the use of the fall back encoding: if the input doesn't have a BOM and + is not valid UTF-8, the conversion will fail. + */ + static void DisableFallbackEncoding(); + + /** + Returns the encoding used by default by wxConvAuto if no other encoding is + explicitly specified in constructor. By default, returns + @c wxFONTENCODING_ISO8859_1 but can be changed using + @ref setdefaultmbencoding() SetFallbackEncoding method. + */ + static wxFontEncoding GetFallbackEncoding(); + + /** + Changes the encoding used by default by wxConvAuto if no other encoding is + explicitly specified in constructor. The default value, which can be retrieved + using @ref getdefaultmbencoding() GetFallbackEncoding, is + @c wxFONTENCODING_ISO8859_1. + + Special values of @c wxFONTENCODING_SYSTEM or + @c wxFONTENCODING_MAX can be used for @e enc parameter to use the + encoding of the current user locale as fall back or not use any encoding for + fall back at all, respectively (just as with the similar constructor + parameter). However @c wxFONTENCODING_DEFAULT value cannot be used here. + */ + static void SetFallbackEncoding(wxFontEncoding enc); +}; diff --git a/interface/cpp.h b/interface/cpp.h new file mode 100644 index 0000000000..3b3140ab52 --- /dev/null +++ b/interface/cpp.h @@ -0,0 +1,40 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: cpp.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + //@{ +/** + These macro return the concatenation of the tokens passed as their arguments. + Unlike when using the preprocessor @c operator, the arguments undergo + the macro expansion before being concatenated. +*/ + wxCONCAT(x1, x2); + wxCONCAT3(x1, x2, x3); + wxCONCAT4(x1, x2, x3, x4); + wxCONCAT5(x1, x2, x3, x4, x5); +//@} + + + /** + Returns the string representation of the given symbol which can be either a + literal or a macro (hence the advantage of using this macro instead of the + standard preprocessor @c # operator which doesn't work with macros). + + Notice that this macro always produces a @c char string, use + wxSTRINGIZE_T to build a wide string Unicode build. + + @sa wxCONCAT +*/ +#define wxSTRINGIZE(x) /* implementation is private */ + +/** + Returns the string representation of the given symbol as either an ASCII or + Unicode string, depending on the current build. This is the Unicode-friendly + equivalent of wxSTRINGIZE. +*/ +#define wxSTRINGIZE_T(x) /* implementation is private */ + diff --git a/interface/cshelp.h b/interface/cshelp.h new file mode 100644 index 0000000000..e4157693e2 --- /dev/null +++ b/interface/cshelp.h @@ -0,0 +1,296 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cshelp.h +// Purpose: documentation for wxHelpProvider class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHelpProvider + @wxheader{cshelp.h} + + wxHelpProvider is an abstract class used by a program implementing + context-sensitive help to + show the help text for the given window. + + The current help provider must be explicitly set by the application using + wxHelpProvider::Set(). + + @library{wxcore} + @category{help} + + @seealso + wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider, + wxHelpControllerHelpProvider, wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint +*/ +class wxHelpProvider +{ +public: + /** + Virtual destructor for any base class. + */ + ~wxHelpProvider(); + + /** + 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. + */ + void AddHelp(wxWindowBase* window, const wxString& text); + + /** + Unlike some other classes, the help provider is not created on demand. + This must be explicitly done by the application. + */ +#define wxHelpProvider* Get() /* implementation is private */ + + //@{ + /** + 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. + */ + wxString GetHelp(const wxWindowBase* window); + void AddHelp(wxWindowID id, const wxString& text); + //@} + + /** + 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. + */ + void RemoveHelp(wxWindowBase* window); + + /** + Get/set the current, application-wide help provider. Returns + the previous one. + */ +#define wxHelpProvider* Set(wxHelpProvider* helpProvider) /* implementation is private */ + + /** + Shows help for the given window. Override this function if the help doesn't + depend on the exact position inside the window, otherwise you need to override + ShowHelpAtPoint(). + + Returns @true if help was shown, or @false if no help was available for this + window. + */ + bool ShowHelp(wxWindowBase* window); + + /** + This function may be overridden to show help for the window when it should + depend on the position inside the window, By default this method forwards to + ShowHelp(), so it is enough to only implement + the latter if the help doesn't depend on the position. + + Returns @true if help was shown, or @false if no help was available for this + window. + + @param window + Window to show help text for. + + @param point + Coordinates of the mouse at the moment of help event emission. + + @param origin + Help event origin, see wxHelpEvent::GetOrigin. + */ + bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point, + wxHelpEvent::Origin origin); +}; + + +/** + @class wxHelpControllerHelpProvider + @wxheader{cshelp.h} + + wxHelpControllerHelpProvider is an implementation of wxHelpProvider which + supports + both context identifiers and plain text help strings. If the help text is an + integer, + it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the + string + in a tooltip as per wxSimpleHelpProvider. If you use this with a + wxCHMHelpController instance + on windows, it will use the native style of tip window instead of wxTipWindow. + + You can use the convenience function @b wxContextId to convert an integer + context + id to a string for passing to wxWindow::SetHelpText. + + @library{wxcore} + @category{help} + + @seealso + wxHelpProvider, wxSimpleHelpProvider, wxContextHelp, wxWindow::SetHelpText, + wxWindow::GetHelpTextAtPoint +*/ +class wxHelpControllerHelpProvider : public wxSimpleHelpProvider +{ +public: + /** + Note that the instance doesn't own the help controller. The help controller + should be deleted separately. + */ + wxHelpControllerHelpProvider(wxHelpControllerBase* hc = @NULL); + + /** + Returns the help controller associated with this help provider. + */ + wxHelpControllerBase* GetHelpController(); + + /** + Sets the help controller associated with this help provider. + */ + void SetHelpController(wxHelpControllerBase* hc); +}; + + +/** + @class wxContextHelp + @wxheader{cshelp.h} + + This class changes the cursor to a query and puts the application into a + 'context-sensitive help mode'. + When the user left-clicks on a window within the specified window, a wxEVT_HELP + event is + sent to that control, and the application may respond to it by popping up some + help. + + For example: + + @code + wxContextHelp contextHelp(myWindow); + @endcode + + There are a couple of ways to invoke this behaviour implicitly: + + Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This will + put a question mark + in the titlebar, and Windows will put the application into context-sensitive + help mode automatically, + with further programming. + Create a wxContextHelpButton, whose predefined behaviour is to create a + context help object. + Normally you will write your application so that this button is only added to a + dialog for non-Windows platforms + (use wxDIALOG_EX_CONTEXTHELP on Windows). + + Note that on Mac OS X, the cursor does not change when in context-sensitive + help mode. + + @library{wxcore} + @category{help} + + @seealso + wxHelpEvent, wxHelpController, wxContextHelpButton +*/ +class wxContextHelp : public wxObject +{ +public: + /** + Constructs a context help object, calling BeginContextHelp() if + @e doNow is @true (the default). + + If @e window is @NULL, the top window is used. + */ + wxContextHelp(wxWindow* window = @NULL, bool doNow = @true); + + /** + Destroys the context help object. + */ + ~wxContextHelp(); + + /** + Puts the application into context-sensitive help mode. @e window is the window + which will be used to catch events; if @NULL, the top window will be used. + + Returns @true if the application was successfully put into context-sensitive + help mode. + This function only returns when the event loop has finished. + */ + bool BeginContextHelp(wxWindow* window = @NULL); + + /** + Ends context-sensitive help mode. Not normally called by the application. + */ + bool EndContextHelp(); +}; + + +/** + @class wxContextHelpButton + @wxheader{cshelp.h} + + Instances of this class may be used to add a question mark button that when + pressed, puts the + application into context-help mode. It does this by creating a wxContextHelp + object which itself + generates a wxEVT_HELP event when the user clicks on a window. + + On Windows, you may add a question-mark icon to a dialog by use of the + wxDIALOG_EX_CONTEXTHELP extra style, but + on other platforms you will have to add a button explicitly, usually next to + OK, Cancel or similar buttons. + + @library{wxcore} + @category{help} + + @seealso + wxBitmapButton, wxContextHelp +*/ +class wxContextHelpButton : public wxBitmapButton +{ +public: + //@{ + /** + Constructor, creating and showing a context help button. + + @param parent + Parent window. Must not be @NULL. + + @param id + Button identifier. Defaults to wxID_CONTEXT_HELP. + + @param pos + Button position. + + @param size + Button size. If wxDefaultSize is specified then the button is sized + appropriately for the question mark bitmap. + + @param style + Window style. + */ + wxContextHelpButton(); + wxContextHelpButton(wxWindow* parent, + wxWindowID id = wxID_CONTEXT_HELP, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW); + //@} +}; + + +/** + @class wxSimpleHelpProvider + @wxheader{cshelp.h} + + wxSimpleHelpProvider is an implementation of wxHelpProvider which supports + only plain text help strings, and shows the string associated with the + control (if any) in a tooltip. + + @library{wxcore} + @category{help} + + @seealso + wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp, + wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint +*/ +class wxSimpleHelpProvider : public wxHelpProvider +{ +public: + +}; diff --git a/interface/ctrlsub.h b/interface/ctrlsub.h new file mode 100644 index 0000000000..78fae3735a --- /dev/null +++ b/interface/ctrlsub.h @@ -0,0 +1,355 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ctrlsub.h +// Purpose: documentation for wxControlWithItems class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxControlWithItems + @wxheader{ctrlsub.h} + + 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 (@c void *) pointers which are simply + stored by the control but not used in any way by it, or typed pointers + (@c wxClientData *) which are owned by the control meaning that the typed + client data (and only it) will be deleted when an item is + @ref wxControlWithItems::delete deleted or the entire control is + @ref wxControlWithItems::clear 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 wxControlWithItems::Append (the version with + client data pointer) or wxControlWithItems::SetClientData. + + @library{wxcore} + @category{FIXME} + + @seealso + wxControlWithItems::Clear +*/ +class wxControlWithItems : public wxControl +{ +public: + //@{ + /** + Appends several items at once to the control. Notice that calling this method + is usually much faster than appending them one by one if you need to add a lot + of items. + + @param item + String to add. + + @param stringsArray + Contains items to append to the control. + + @param strings + Array of strings of size n. + + @param n + Number of items in the strings array. + + @param clientData + Array of client data pointers of size n to associate with the new items. + + @returns When appending a single item, the return value is the index of + the newly added item which may be different from the + last one if the control is sorted (e.g. has wxLB_SORT + or wxCB_SORT style). + */ + int Append(const wxString& item); + int Append(const wxString& item, void * clientData); + int Append(const wxString& item, wxClientData * clientData); + void Append(const wxArrayString& strings); + void Append(unsigned int n, const wxString* strings); + void Append(unsigned int n, const wxString* strings, + void ** clientData); + void Append(unsigned int n, const wxString* strings, + wxClientData ** clientData); + //@} + + /** + Removes all items from the control. + + @e Clear() also deletes the client data of the existing items if it is owned + by the control. + */ + void Clear(); + + /** + Deletes an item from the control. The client data associated with the item + will be also deleted if it is owned by the control. + + Note that it is an error (signalled by an assert failure in debug builds) to + remove an item with the index negative or greater or equal than the number of + items in the control. + + @param n + The zero-based item index. + + @sa Clear() + */ + void Delete(unsigned int n); + + /** + Finds an item whose label matches the given string. + + @param string + String to find. + + @param caseSensitive + Whether search is case sensitive (default is not). + + @returns The zero-based position of the item, or wxNOT_FOUND if the + string was not found. + */ + int FindString(const wxString& string, + bool caseSensitive = @false); + + /** + Returns a pointer to the client data associated with the given item (if any). + It is an error to call this function for a control which doesn't have untyped + client data at all although it is ok to call it even if the given item doesn't + have any client data associated with it (but other items do). + + @param n + The zero-based position of the item. + + @returns A pointer to the client data, or @NULL if not present. + */ + void * GetClientData(unsigned int n); + + /** + Returns a pointer to the client data associated with the given item (if any). + It is an error to call this function for a control which doesn't have typed + client data at all although it is ok to call it even if the given item doesn't + have any client data associated with it (but other items do). + + @param n + The zero-based position of the item. + + @returns A pointer to the client data, or @NULL if not present. + */ + wxClientData * GetClientObject(unsigned int n); + + /** + Returns the number of items in the control. + + @sa IsEmpty() + */ + unsigned int GetCount(); + + /** + Returns the index of the selected item or @c wxNOT_FOUND if no item is + selected. + + @returns The position of the current selection. + + @remarks This method can be used with single selection list boxes only, + you should use wxListBox::GetSelections for the list + boxes with wxLB_MULTIPLE style. + + @sa SetSelection(), GetStringSelection() + */ + int GetSelection(); + + /** + Returns the label of the item with the given index. + + @param n + The zero-based index. + + @returns The label of the item or an empty string if the position was + invalid. + */ + wxString GetString(unsigned int n); + + /** + Returns the label of the selected item or an empty string if no item is + selected. + + @sa GetSelection() + */ + wxString GetStringSelection(); + + /** + Returns the array of the labels of all items in the control. + */ + wxArrayString GetStrings(); + + //@{ + /** + Inserts several items at once into the control. Notice that calling this method + is usually much faster than inserting them one by one if you need to insert a + lot + of items. + + @param item + String to add. + + @param pos + Position to insert item before, zero based. + + @param stringsArray + Contains items to insert into the control content + + @param strings + Array of strings of size n. + + @param n + Number of items in the strings array. + + @param clientData + Array of client data pointers of size n to associate with the new items. + + @returns The return value is the index of the newly inserted item. If the + insertion failed for some reason, -1 is returned. + */ + int Insert(const wxString& item, unsigned int pos); + int Insert(const wxString& item, unsigned int pos, + void * clientData); + int Insert(const wxString& item, unsigned int pos, + wxClientData * clientData); + void Insert(const wxArrayString& strings, unsigned int pos); + void Insert(const wxArrayString& strings, unsigned int pos); + void Insert(unsigned int n, const wxString* strings, + unsigned int pos); + void Insert(unsigned int n, const wxString* strings, + unsigned int pos, + void ** clientData); + void Insert(unsigned int n, const wxString* strings, + unsigned int pos, + wxClientData ** clientData); + //@} + + /** + Returns @true if the control is empty or @false if it has some items. + + @sa GetCount() + */ + bool IsEmpty(); + + /** + This is the same as SetSelection() and + exists only because it is slightly more natural for controls which support + multiple selection. + */ + void Select(int n); + + //@{ + /** + Replaces the current control contents with the given items. Notice that calling + this method is much faster than appending the items one by one if you need to + append a lot of them. + + @param item + The single item to insert into the control. + + @param stringsArray + Contains items to set as control content. + + @param strings + Raw C++ array of strings. Only used in conjunction with 'n'. + + @param n + Number of items passed in 'strings'. Only used in conjunction with 'strings'. + + @param clientData + Client data to associate with the item(s). + + @returns When the control is sorted (e.g. has wxLB_SORT or wxCB_SORT + style) the return value could be different from + (GetCount() - 1). When setting a single item to the + container, the return value is the index of the newly + added item which may be different from the last one + if the control is sorted (e.g. has wxLB_SORT or + wxCB_SORT style). + */ + int Set(const wxString& item); + int Set(const wxString& item, void * clientData); + int Set(const wxString& item, wxClientData * clientData); + void Set(const wxArrayString& stringsArray); + void Set(unsigned int n, const wxString* strings); + void Set(unsigned int n, const wxString* strings, + void ** clientData); + void Set(unsigned int n, const wxString* strings, + wxClientData ** clientData); + //@} + + /** + Associates the given untyped client data pointer with the given item. Note that + it is an error to call this function if any typed client data pointers had been + associated with the control items before. + + @param n + The zero-based item index. + + @param data + The client data to associate with the item. + */ + void SetClientData(unsigned int n, void * data); + + /** + Associates the given typed client data pointer with the given item: the + @e data object will be deleted when the item is deleted (either explicitly + by using @ref delete() 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. + + @param n + The zero-based item index. + + @param data + The client data to associate with the item. + */ + void SetClientObject(unsigned int n, wxClientData * data); + + /** + Sets the selection to the given item @e n or removes the selection entirely + if @e n == @c wxNOT_FOUND. + + Note that this does not cause any command events to be emitted nor does it + deselect any other items in the controls which support multiple selections. + + @param n + The string position to select, starting from zero. + + @sa SetString(), SetStringSelection() + */ + void SetSelection(int n); + + /** + Sets the label for the given item. + + @param n + The zero-based item index. + + @param string + The label to set. + */ + void SetString(unsigned int n, const wxString& string); + + /** + Selects the item with the specified string in the control. This doesn't cause + any command events to be emitted. + + @param string + The string to select. + + @returns @true if the specified string has been selected, @false if it + wasn't found in the control. + */ + bool SetStringSelection(const wxString& string); +}; diff --git a/interface/cursor.h b/interface/cursor.h new file mode 100644 index 0000000000..390252858e --- /dev/null +++ b/interface/cursor.h @@ -0,0 +1,282 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cursor.h +// Purpose: documentation for wxCursor class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCursor + @wxheader{cursor.h} + + A cursor is a small bitmap usually used for denoting where the mouse + pointer is, with a picture that might indicate the interpretation of a + mouse click. As with icons, cursors in X and MS Windows are created + in a different manner. Therefore, separate cursors will be created for the + different environments. Platform-specific methods for creating a @b 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. + + @library{wxcore} + @category{gdi} + + @stdobjects + Objects: + wxNullCursor + Pointers: + wxSTANDARD_CURSOR + + wxHOURGLASS_CURSOR + + wxCROSS_CURSOR + + @seealso + wxBitmap, wxIcon, wxWindow::SetCursor, ::wxSetCursor +*/ +class wxCursor : public wxBitmap +{ +public: + //@{ + /** + Copy constructor, uses @ref overview_trefcount "reference counting". + + @param bits + An array of bits. + + @param maskBits + Bits for a mask bitmap. + + @param width + Cursor width. + + @param height + Cursor height. + + @param hotSpotX + Hotspot x coordinate. + + @param hotSpotY + Hotspot y coordinate. + + @param type + Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM. Under + Windows, + it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under MacOS, it defaults to + wxBITMAP_TYPE_MACCURSOR_RESOURCE. + + Under X, the permitted cursor types are: + + + wxBITMAP_TYPE_XBM + + + Load an X bitmap file. + + Under Windows, the permitted types are: + + + wxBITMAP_TYPE_CUR + + + Load a cursor from a .cur cursor file (only if USE_RESOURCE_LOADING_IN_MSW + is enabled in setup.h). + + wxBITMAP_TYPE_CUR_RESOURCE + + + Load a Windows resource (as specified in the .rc file). + + wxBITMAP_TYPE_ICO + + + Load a cursor from a .ico icon file (only if USE_RESOURCE_LOADING_IN_MSW + is enabled in setup.h). Specify hotSpotX and hotSpotY. + + @param cursorId + A stock cursor identifier. May be one of: + + + wxCURSOR_ARROW + + + A standard arrow cursor. + + wxCURSOR_RIGHT_ARROW + + + A standard arrow cursor + pointing to the right. + + wxCURSOR_BLANK + + + Transparent cursor. + + wxCURSOR_BULLSEYE + + + Bullseye cursor. + + wxCURSOR_CHAR + + + Rectangular character cursor. + + wxCURSOR_CROSS + + + A cross cursor. + + wxCURSOR_HAND + + + A hand cursor. + + wxCURSOR_IBEAM + + + An I-beam cursor (vertical line). + + wxCURSOR_LEFT_BUTTON + + + Represents a mouse with the left button depressed. + + wxCURSOR_MAGNIFIER + + + A magnifier icon. + + wxCURSOR_MIDDLE_BUTTON + + + Represents a mouse with the middle button depressed. + + wxCURSOR_NO_ENTRY + + + A no-entry sign cursor. + + wxCURSOR_PAINT_BRUSH + + + A paintbrush cursor. + + wxCURSOR_PENCIL + + + A pencil cursor. + + wxCURSOR_POINT_LEFT + + + A cursor that points left. + + wxCURSOR_POINT_RIGHT + + + A cursor that points right. + + wxCURSOR_QUESTION_ARROW + + + An arrow and question mark. + + wxCURSOR_RIGHT_BUTTON + + + Represents a mouse with the right button depressed. + + wxCURSOR_SIZENESW + + + A sizing cursor pointing NE-SW. + + wxCURSOR_SIZENS + + + A sizing cursor pointing N-S. + + wxCURSOR_SIZENWSE + + + A sizing cursor pointing NW-SE. + + wxCURSOR_SIZEWE + + + A sizing cursor pointing W-E. + + wxCURSOR_SIZING + + + A general sizing cursor. + + wxCURSOR_SPRAYCAN + + + A spraycan cursor. + + wxCURSOR_WAIT + + + A wait cursor. + + wxCURSOR_WATCH + + + A watch cursor. + + wxCURSOR_ARROWWAIT + + + A cursor with both an arrow and + an hourglass, (windows.) + + Note that not all cursors are available on all platforms. + + @param cursor + Pointer or reference to a cursor to copy. + */ + wxCursor(); + wxCursor(const char bits[], int width, int height, + int hotSpotX=-1, int hotSpotY=-1, + const char maskBits[]=@NULL, + wxColour* fg=@NULL, + wxColour* bg=@NULL); + wxCursor(const wxString& cursorName, long type, + int hotSpotX=0, int hotSpotY=0); + wxCursor(int cursorId); + wxCursor(const wxImage& image); + wxCursor(const wxCursor& cursor); + //@} + + /** + Destroys the cursor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + + A cursor can be reused for more + than one window, and does not get destroyed when the window is + destroyed. wxWidgets destroys all cursors on application exit, although + it is best to clean them up explicitly. + */ + ~wxCursor(); + + /** + Returns @true if cursor data is present. + */ +#define bool IsOk() /* implementation is private */ + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxCursor operator =(const wxCursor& cursor); +}; diff --git a/interface/dataobj.h b/interface/dataobj.h new file mode 100644 index 0000000000..4480ea98e3 --- /dev/null +++ b/interface/dataobj.h @@ -0,0 +1,711 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dataobj.h +// Purpose: documentation for wxCustomDataObject class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCustomDataObject + @wxheader{dataobj.h} + + wxCustomDataObject is a specialization of + wxDataObjectSimple for some + application-specific data in arbitrary (either custom or one of the standard + ones). The only restriction is that it is supposed that this data can be + copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to make + it contain a C++ object (though C struct is fine). + + By default, wxCustomDataObject stores the data inside in a buffer. To put the + data into the buffer you may use either + wxCustomDataObject::SetData or + wxCustomDataObject::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. + + @library{wxcore} + @category{dnd} + + @seealso + wxDataObject +*/ +class wxCustomDataObject : public wxDataObjectSimple +{ +public: + /** + The constructor accepts a @e format argument which specifies the (single) + format supported by this object. If it isn't set here, + wxDataObjectSimple::SetFormat should be used. + */ + wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid); + + /** + The destructor will free the data 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 @c Free(), you + should override the destructor in your class as well (which would probably + just call the derived class' version of @c Free()). + */ + ~wxCustomDataObject(); + + /** + This function is called to allocate @e size bytes of memory from SetData(). + The default version just uses the operator new. + */ + virtual void * Alloc(size_t size); + + /** + This function is called when the data is freed, you may override it to anything + you want (or may be nothing at all). The default version calls operator + delete[] on the data. + */ + virtual void Free(); + + /** + Returns a pointer to the data. + */ + virtual void * GetData(); + + /** + Returns the data size in bytes. + */ + virtual size_t GetSize(); + + /** + Set the data. The data object will make an internal copy. + */ + virtual void SetData(size_t size, const void data); + + /** + Like SetData(), but doesn't copy the data - + instead the object takes ownership of the pointer. + + @b wxPython note: This method expects a string in wxPython. You can pass + nearly any object by pickling it first. + */ + virtual void TakeData(size_t size, const void data); +}; + + +/** + @class wxDataObjectComposite + @wxheader{dataobj.h} + + wxDataObjectComposite is the simplest + wxDataObject derivation which may be used to support + multiple formats. It contains several + wxDataObjectSimple objects and supports any + format supported by at least one of them. Only one of these data objects is + @e preferred (the first one if not explicitly changed by using the second + parameter of wxDataObjectComposite::Add) and its format determines + the preferred format of the composite data object as well. + + See wxDataObject documentation for the reasons why you + might prefer to use wxDataObject directly instead of wxDataObjectComposite for + efficiency reasons. + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_wxdndoverview "Clipboard and drag and drop overview", + wxDataObject, wxDataObjectSimple, wxFileDataObject, wxTextDataObject, wxBitmapDataObject +*/ +class wxDataObjectComposite : public wxDataObject +{ +public: + /** + The default constructor. + */ + wxDataObjectComposite(); + + /** + Adds the @e dataObject to the list of supported objects and it becomes the + preferred object if @e preferred is @true. + */ +#define void Add(wxDataObjectSimple dataObject, bool preferred = @false) /* implementation is private */ + + /** + Report the format passed to the SetData method. This should be the + format of the data object within the composite that recieved data from + the clipboard or the DnD operation. You can use this method to find + out what kind of data object was recieved. + */ + wxDataFormat GetReceivedFormat(); +}; + + +/** + @class wxDataObjectSimple + @wxheader{dataobj.h} + + This is the simplest possible implementation of the + wxDataObject class. The data object of (a class derived + from) this class only supports one format, so the number of virtual functions + to be implemented is reduced. + + Notice that this is still an abstract base class and cannot be used but should + be derived from. + + @b wxPython note: If you wish to create a derived wxDataObjectSimple class in + wxPython you should derive the class from wxPyDataObjectSimple + in order to get Python-aware capabilities for the various virtual + methods. + + @b wxPerl note: In wxPerl, you need to derive your data object class + from Wx::PlDataObjectSimple. + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_wxdndoverview "Clipboard and drag and drop overview", @ref + overview_samplednd "DnD sample", wxFileDataObject, wxTextDataObject, wxBitmapDataObject +*/ +class wxDataObjectSimple : public wxDataObject +{ +public: + /** + Constructor accepts the supported format (none by default) which may also be + set later with SetFormat(). + */ + wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid); + + /** + Copy the data to the buffer, return @true on success. Must be implemented in the + derived class if the object supports rendering its data. + */ + virtual bool GetDataHere(void buf); + + /** + Gets the size of our data. Must be implemented in the derived class if the + object supports rendering its data. + */ + virtual size_t GetDataSize(); + + /** + Returns the (one and only one) format supported by this object. It is supposed + that the format is supported in both directions. + */ + const wxDataFormat GetFormat(); + + /** + Copy the data from the buffer, return @true on success. Must be implemented in + the derived class if the object supports setting its data. + + @b wxPython note: When implementing this method in wxPython, the data comes + as a single string parameter rather than the two shown here. + */ + virtual bool SetData(size_t len, const void buf); + + /** + Sets the supported format. + */ + void SetFormat(const wxDataFormat& format); +}; + + +/** + @class wxBitmapDataObject + @wxheader{dataobj.h} + + wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It can + be used without change to paste data into the + wxClipboard or a wxDropSource. A + user may wish to derive a new class from this class for providing a bitmap + on-demand in order to minimize memory consumption when offering data in several + formats, such as a bitmap and GIF. + + @b wxPython note: If you wish to create a derived wxBitmapDataObject class in + wxPython you should derive the class from wxPyBitmapDataObject + in order to get Python-aware capabilities for the various virtual + methods. + + @library{wxcore} + @category{dnd} + + @seealso + @ref overview_wxdndoverview "Clipboard and drag and drop overview", + wxDataObject, wxDataObjectSimple, wxFileDataObject, wxTextDataObject, wxDataObject +*/ +class wxBitmapDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor, optionally passing a bitmap (otherwise use + SetBitmap() later). + */ + wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap); + + /** + Returns the bitmap associated with the data object. You may wish to override + this method when offering data on-demand, but this is not required by + wxWidgets' internals. Use this method to get data in bitmap form from + the wxClipboard. + */ + virtual wxBitmap GetBitmap(); + + /** + Sets the bitmap associated with the data object. This method is called when the + data object receives data. Usually there will be no reason to override this + function. + */ + virtual void SetBitmap(const wxBitmap& bitmap); +}; + + +/** + @class wxDataFormat + @wxheader{dataobj.h} + + A wxDataFormat is an encapsulation of a platform-specific format handle which + is used by the system for the clipboard and drag and drop operations. The + applications are usually only interested in, for example, pasting data from the + clipboard only if the data is in a format the program understands and a data + format is something which uniquely identifies this format. + + On the system level, a data format is usually just a number (@c CLIPFORMAT + under Windows or @c Atom under X11, for example) and the standard formats + are, indeed, just numbers which can be implicitly converted to wxDataFormat. + The standard formats are: + + + + 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 @c wxDataFormat::NativeFormat which is + the type used by the underlying platform for data formats). + + Aside the standard formats, the application may also use custom formats which + are identified by their names (strings) and not numeric identifiers. Although + internally custom format must be created (or @e registered) first, you + shouldn't care about it because it is done automatically the first time the + wxDataFormat object corresponding to a given format name is created. The only + implication of this is that you should avoid having global wxDataFormat objects + with non-default constructor because their constructors are executed before the + program has time to perform all necessary initialisations and so an attempt to + do clipboard format registration at this time will usually lead to a crash! + + @library{wxbase} + @category{dnd} + + @seealso + @ref overview_wxdndoverview "Clipboard and drag and drop overview", @ref + overview_samplednd "DnD sample", wxDataObject +*/ +class wxDataFormat +{ +public: + /** + Constructs a data format object for a custom format identified by its name + @e format. + */ + wxDataFormat(const wxChar format); + + /** + Returns the name of a custom format (this function will fail for a standard + format). + */ + wxString GetId(); + + /** + Returns the platform-specific number identifying the format. + */ + NativeFormat GetType(); + + /** + Sets the format to be the custom format identified by the given name. + */ + void SetId(const wxChar format); + + /** + Sets the format to the given value, which should be one of wxDF_XXX constants. + */ + void SetType(NativeFormat format); + + /** + Returns @true if the formats are different. + */ + bool operator !=(const wxDataFormat& format); + + /** + Returns @true if the formats are equal. + */ + bool operator ==(const wxDataFormat& format); +}; + + +/** + @class wxURLDataObject + @wxheader{dataobj.h} + + wxURLDataObject is a wxDataObject containing an URL + and can be used e.g. when you need to put an URL on or retrieve it from the + clipboard: + + @code + wxTheClipboard-SetData(new wxURLDataObject(url)); + @endcode + + @library{wxcore} + @category{dnd} + + @seealso + @ref overview_wxdndoverview "Clipboard and drag and drop overview", wxDataObject +*/ +class wxURLDataObject +{ +public: + /** + Constructor, may be used to initialize the URL. If @e url is empty, + SetURL() can be used later. + */ + wxURLDataObject(const wxString& url = wxEmptyString); + + /** + Returns the URL stored by this object, as a string. + */ +#define wxString GetURL() /* implementation is private */ + + /** + Sets the URL stored by this object. + */ +#define void SetURL(const wxString& url) /* implementation is private */ +}; + + +/** + @class wxDataObject + @wxheader{dataobj.h} + + A wxDataObject represents data that can be copied to or from the clipboard, or + dragged and dropped. The important thing about wxDataObject is that this is a + 'smart' piece of data unlike 'dumb' data containers such as memory + buffers or files. Being 'smart' here means that the data object itself should + know what data formats it supports and how to render itself in each of + its supported formats. + + A supported format, incidentally, is exactly the format in which the data can + be requested from a data object or from which the data object may be set. In + the general case, an object may support different formats on 'input' and + 'output', i.e. it may be able to render itself in a given format but not be + created from data on this format or vice versa. wxDataObject defines an + enumeration type + + @code + enum Direction + { + Get = 0x01, // format is supported by GetDataHere() + Set = 0x02 // format is supported by SetData() + }; + @endcode + + 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): + + + + @b 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. + + + @b 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). + + + @b 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). + + + @b 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, + wxBitmapDataObject and + wxURLDataObject + which can be used without change. + + You may also derive your own data object classes from + wxCustomDataObject for user-defined types. The + format of user-defined data is given as a mime-type string literal, such as + "application/word" or "image/png". These strings are used as they are under + Unix (so far only GTK+) to identify a format and are translated into their + Windows equivalent under Win32 (using the OLE IDataObject for data exchange to + and from the clipboard and for drag and drop). Note that the format string + translation under Windows is not yet finished. + + @b wxPython note: At this time this class is not directly usable from wxPython. + Derive a class from wxPyDataObjectSimple + instead. + + @b wxPerl note: This class is not currently usable from wxPerl; you may + use Wx::PlDataObjectSimple instead. + + @library{wxcore} + @category{dnd} + + @seealso + @ref overview_wxdndoverview "Clipboard and drag and drop overview", @ref + overview_samplednd "DnD sample", wxFileDataObject, wxTextDataObject, wxBitmapDataObject, wxCustomDataObject, wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget +*/ +class wxDataObject +{ +public: + /** + Constructor. + */ + wxDataObject(); + + /** + Destructor. + */ + ~wxDataObject(); + + /** + Copy all supported formats in the given direction to the array pointed to by + @e formats. There is enough space for GetFormatCount(dir) formats in it. + */ + virtual void GetAllFormats(wxDataFormat * formats, + Direction dir = Get); + + /** + The method will write the data of the format @e format in the buffer @e buf and + return @true on success, @false on failure. + */ + virtual bool GetDataHere(const wxDataFormat& format, void buf); + + /** + Returns the data size of the given format @e format. + */ + virtual size_t GetDataSize(const wxDataFormat& format); + + /** + Returns the number of available formats for rendering or setting the data. + */ + virtual size_t GetFormatCount(Direction dir = Get); + + /** + Returns the preferred format for either rendering the data (if @e dir is @c Get, + its default value) or for setting it. Usually this will be the + native format of the wxDataObject. + */ + virtual wxDataFormat GetPreferredFormat(Direction dir = Get); + + /** + Set the data in the format @e format of the length @e len provided in the + buffer @e buf. + + Returns @true on success, @false on failure. + */ + virtual bool SetData(const wxDataFormat& format, size_t len, + const void buf); +}; + + +/** + @class wxTextDataObject + @wxheader{dataobj.h} + + wxTextDataObject is a specialization of wxDataObject for text data. It can be + used without change to paste data into the wxClipboard + or a wxDropSource. A user may wish to derive a new + class from this class for providing text on-demand in order to minimize memory + consumption when offering data in several formats, such as plain text and RTF + because by default the text is stored in a string in this class, but it might + as well be generated when requested. For this, + wxTextDataObject::GetTextLength and + wxTextDataObject::GetText will have to be overridden. + + Note that if you already have the text inside a string, you will not achieve + any efficiency gain by overriding these functions because copying wxStrings is + already a very efficient operation (data is not actually copied because + wxStrings are reference counted). + + @b wxPython note: If you wish to create a derived wxTextDataObject class in + wxPython you should derive the class from wxPyTextDataObject + in order to get Python-aware capabilities for the various virtual + methods. + + @library{wxcore} + @category{dnd} + + @seealso + @ref overview_wxdndoverview "Clipboard and drag and drop overview", + wxDataObject, wxDataObjectSimple, wxFileDataObject, wxBitmapDataObject +*/ +class wxTextDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor, may be used to initialise the text (otherwise + SetText() should be used later). + */ + wxTextDataObject(const wxString& text = wxEmptyString); + + /** + Returns the text associated with the data object. You may wish to override + this method when offering data on-demand, but this is not required by + wxWidgets' internals. Use this method to get data in text form from + the wxClipboard. + */ + virtual wxString GetText(); + + /** + Returns the data size. By default, returns the size of the text data + set in the constructor or using SetText(). + This can be overridden to provide text size data on-demand. It is recommended + to return the text length plus 1 for a trailing zero, but this is not + strictly required. + */ + virtual size_t GetTextLength(); + + /** + Sets the text associated with the data object. This method is called + when the data object receives the data and, by default, copies the text into + the member variable. If you want to process the text on the fly you may wish to + override this function. + */ + virtual void SetText(const wxString& strText); +}; + + +/** + @class wxFileDataObject + @wxheader{dataobj.h} + + wxFileDataObject is a specialization of wxDataObject + for file names. The program works with it just as if it were a list of absolute + file + names, but internally it uses the same format as + Explorer and other compatible programs under Windows or GNOME/KDE filemanager + under Unix which makes it possible to receive files from them using this + class. + + @b Warning: Under all non-Windows platforms this class is currently + "input-only", i.e. you can receive the files from another application, but + copying (or dragging) file(s) from a wxWidgets application is not currently + supported. PS: GTK2 should work as well. + + @library{wxcore} + @category{dnd} + + @seealso + wxDataObject, wxDataObjectSimple, wxTextDataObject, wxBitmapDataObject, + wxDataObject +*/ +class wxFileDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor. + */ + wxFileDataObject(); + + /** + @b MSW only: adds a file to the file list represented by this data object. + */ + virtual void AddFile(const wxString& file); + + /** + Returns the array of file names. + */ + const wxArrayString GetFilenames(); +}; diff --git a/interface/dataview.h b/interface/dataview.h new file mode 100644 index 0000000000..3c0453696d --- /dev/null +++ b/interface/dataview.h @@ -0,0 +1,1919 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dataview.h +// Purpose: documentation for wxDataViewIconText class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDataViewIconText + @wxheader{dataview.h} + + wxDataViewIconText is used by + wxDataViewIconTextRenderer + for data transfer. This class can be converted to a from + a wxVariant. + + @library{wxbase} + @category{FIXME} +*/ +class wxDataViewIconText : public wxObject +{ +public: + //@{ + /** + Constructor. + */ + wxDataViewIconText(const wxString& text = wxEmptyString, + const wxIcon& icon = wxNullIcon); + wxDataViewIconText(const wxDataViewIconText& other); + //@} + + /** + Gets the icon. + */ + const wxIcon GetIcon(); + + /** + Gets the text. + */ + wxString GetText(); + + /** + Set the icon. + */ + void SetIcon(const wxIcon& icon); + + /** + Set the text. + */ + void SetText(const wxString& text); +}; + + +/** + @class wxDataViewEvent + @wxheader{dataview.h} + + wxDataViewEvent - the event class for the wxDataViewCtrl notifications + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewEvent : public wxNotifyEvent +{ +public: + //@{ + /** + + */ + wxDataViewEvent(wxEventType commandType = wxEVT_@NULL, + int winid = 0); + wxDataViewEvent(const wxDataViewEvent& event); + //@} + + /** + Used to clone the event. + */ + wxEvent* Clone(); + + /** + Returns the position of the column in the control or -1 + if no column field was set by the event emitter. + */ + int GetColumn(); + + /** + Returns a pointer to the wxDataViewColumn from which + the event was emitted or @NULL. + */ + wxDataViewColumn* GetDataViewColumn(); + + /** + Returns the wxDataViewModel associated with the event. + */ + wxDataViewModel* GetModel(); + + /** + Returns a the position of a context menu event in screen coordinates. + */ + wxPoint GetPosition(); + + /** + Returns a reference to a value. + */ + const wxVariant GetValue(); + + /** + + */ + void SetColumn(int col); + + /** + For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. + */ + void SetDataViewColumn(wxDataViewColumn* col); + + /** + + */ + void SetModel(wxDataViewModel* model); + + /** + + */ + void SetValue(const wxVariant& value); +}; + + +/** + @class wxDataViewIconTextRenderer + @wxheader{dataview.h} + + The wxDataViewIconTextRenderer class is used to display text with + a small icon next to it as it is typically done in a file manager. + This classes uses the wxDataViewIconText + helper class to store its data. wxDataViewIonText can be converted + to a from a wxVariant using the left shift + operator. + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewIconTextRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT); +}; + + +/** + @class wxDataViewIndexListModel + @wxheader{dataview.h} + + wxDataViewIndexListModel is a specialized data model which lets + you address an item by its position (row) rather than its + wxDataViewItem (which you can obtain from this class). + This model also provides its own + wxDataViewIndexListModel::Compare method + which sorts the model's data by the index. + + This model is special in the it is implemented differently under OS X + and other platforms. Under OS X a wxDataViewItem is always persistent + and this is also the case for this class. Under other platforms, the + meaning of a wxDataViewItem is changed to reflect a row number for + wxDataViewIndexListModel. The consequence of this is that + wxDataViewIndexListModel can be used as a virtual model with an + almost infinate number of items on platforms other than OS X. + + @library{wxbase} + @category{FIXME} +*/ +class wxDataViewIndexListModel : public wxDataViewModel +{ +public: + /** + Constructor. + */ + wxDataViewIndexListModel(unsigned int initial_size = 0); + + /** + Destructor. + */ + ~wxDataViewIndexListModel(); + + /** + Compare method that sorts the items by their index. + */ + int Compare(const wxDataViewItem& item1, + const wxDataViewItem& item2, + unsigned int column, bool ascending); + + /** + Oberride this to indicate that the row has special font attributes. + This only affects the + wxDataViewTextRendererText renderer. + + See also wxDataViewItemAttr. + */ + bool GetAttr(unsigned int row, unsigned int col, + wxDataViewItemAttr& attr); + + /** + Returns the wxDataViewItem at the given @e row. + */ + wxDataViewItem GetItem(unsigned int row); + + /** + Returns the position of given @e item. + */ + unsigned int GetRow(const wxDataViewItem& item); + + /** + Override this to allow getting values from the model. + */ + void GetValue(wxVariant& variant, unsigned int row, + unsigned int col); + + /** + Call this after if the data has to be read again from + the model. This is useful after major changes when + calling the methods below (possibly thousands of times) + doesn't make sense. + */ + void Reset(unsigned int new_size); + + /** + Call this after a row has been appended to the model. + */ + void RowAppended(); + + /** + Call this after a row has been changed. + */ + void RowChanged(unsigned int row); + + /** + Call this after a row has been deleted. + */ + void RowDeleted(unsigned int row); + + /** + Call this after a row has been inserted at the given position. + */ + void RowInserted(unsigned int before); + + /** + Call this after a row has been prepended to the model. + */ + void RowPrepended(); + + /** + Call this after a value has been changed. + */ + void RowValueChanged(unsigned int row, unsigned int col); + + /** + Call this after rows have been deleted. The array will internally + get copied and sorted in descending order so that the rows with + the highest position will be deleted first. + */ + void RowsDeleted(const wxArrayInt& rows); + + /** + Called in order to set a value in the model. + */ + bool SetValue(const wxVariant& variant, unsigned int row, + unsigned int col); +}; + + +/** + @class wxDataViewModel + @wxheader{dataview.h} + + wxDataViewModel is the base class for all data model to be + displayed by a wxDataViewCtrl. + All other models derive from it and must implement its + pure virtual functions in order to define a complete + data model. In detail, you need to override + wxDataViewModel::IsContainer, + wxDataViewModel::GetParent, + wxDataViewModel::GetChildren, + wxDataViewModel::GetColumnCount, + wxDataViewModel::GetColumnType and + wxDataViewModel::GetValue in order to + define the data model which acts as an interface between + your actual data and the wxDataViewCtrl. Since you will + usually also allow the wxDataViewCtrl to change your data + through its graphical interface, you will also have to override + wxDataViewModel::SetValue which the + wxDataViewCtrl will call when a change to some data has been + commited. + + wxDataViewModel (as indeed the entire wxDataViewCtrl + code) is using wxVariant to store data and + its type in a generic way. wxVariant can be extended to contain + almost any data without changes to the original class. + + The data that is presented through this data model is expected + to change at run-time. You need to inform the data model when + a change happened. Depending on what happened you need to call + one of the following methods: + wxDataViewModel::ValueChanged, + wxDataViewModel::ItemAdded, + wxDataViewModel::ItemDeleted, + wxDataViewModel::ItemChanged, + wxDataViewModel::Cleared. There are + plural forms for notification of addition, change + or removal of several item at once. See + wxDataViewModel::ItemsAdded, + wxDataViewModel::ItemsDeleted, + wxDataViewModel::ItemsChanged. + + Note that wxDataViewModel does not define the position or + index of any item in the control because different controls + might display the same data differently. wxDataViewModel does + provide a wxDataViewModel::Compare method + which the wxDataViewCtrl may use to sort the data either + in conjunction with a column header or without (see + wxDataViewModel::HasDefaultCompare). + + This class maintains a list of + wxDataViewModelNotifier + which link this class to the specific implementations on the + supported platforms so that e.g. calling + wxDataViewModel::ValueChanged + on this model will just call + wxDataViewModelNotifier::ValueChanged + for each notifier that has been added. You can also add + your own notifier in order to get informed about any changes + to the data in the list model. + + Currently wxWidgets provides the following models apart + from the base model: + wxDataViewIndexListModel, + wxDataViewTreeStore. + + Note that wxDataViewModel is reference counted, derives from + wxObjectRefData and cannot be deleted + directly as it can be shared by several wxDataViewCtrls. This + implies that you need to decrease the reference count after + associating the model with a control like this: + + @code + wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL ); + wxDataViewModel *musicModel = new MyMusicModel; + m_musicCtrl-AssociateModel( musicModel ); + musicModel-DecRef(); // avoid memory leak !! + // add columns now + @endcode + + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewModel : public wxObjectRefData +{ +public: + /** + Constructor. + */ + wxDataViewModel(); + + /** + Destructor. This should not be called directly. Use DecRef() instead. + */ + ~wxDataViewModel(); + + /** + Adds a wxDataViewModelNotifier + to the model. + */ + void AddNotifier(wxDataViewModelNotifier* notifier); + + /** + Called to inform the model that all data has been cleared. The + control will reread the data from the model again. + */ + virtual bool Cleared(); + + /** + The compare function to be used by control. The default compare function + sorts by container and other items separately and in ascending order. + Override this for a different sorting behaviour. + + See also HasDefaultCompare(). + */ + virtual int Compare(const wxDataViewItem& item1, + const wxDataViewItem& item2, + unsigned int column, + bool ascending); + + /** + Oberride this to indicate that the item has special font attributes. + This only affects the + wxDataViewTextRendererText renderer. + + See also wxDataViewItemAttr. + */ + bool GetAttr(const wxDataViewItem& item, unsigned int col, + wxDataViewItemAttr& attr); + + /** + Override this so the control can query the child items of + an item. Returns the number of items. + */ + virtual unsigned int GetChildren(const wxDataViewItem& item, + wxDataViewItemArray& children); + + /** + Override this to indicate the number of columns in the model. + */ + virtual unsigned int GetColumnCount(); + + /** + Override this to indicate what type of data is stored in the + column specified by @e col. This should return a string + indicating the type of data as reported by wxVariant. + */ + virtual wxString GetColumnType(unsigned int col); + + /** + Override this to indicate which wxDataViewItem representing the parent + of @e item or an invalid wxDataViewItem if the the root item is + the parent item. + */ + virtual wxDataViewItem GetParent(const wxDataViewItem& item); + + /** + Override this to indicate the value of @e item + A wxVariant is used to store the data. + */ + virtual void GetValue(wxVariant& variant, + const wxDataViewItem& item, + unsigned int col); + + /** + Override this method to indicate if a container item merely + acts as a headline (or for categorisation) or if it also + acts a normal item with entries for futher columns. By + default returns @e @false. + */ + virtual bool HasContainerColumns(const wxDataViewItem& item); + + /** + Override this to indicate that the model provides a default compare + function that the control should use if no wxDataViewColumn has been + chosen for sorting. Usually, the user clicks on a column header for + sorting, the data will be sorted alphanumerically. If any other + order (e.g. by index or order of appearance) is required, then this + should be used. See also wxDataViewIndexListModel + for a model which makes use of this. + */ + virtual bool HasDefaultCompare(); + + /** + Override this to indicate of @e item is a container, i.e. if + it can have child items. + */ + virtual bool IsContainer(const wxDataViewItem& item); + + /** + Call this to inform the model that an item has been added + to the data. + */ + virtual bool ItemAdded(const wxDataViewItem& parent, + const wxDataViewItem& item); + + /** + Call this to inform the model that an item has changed. + + This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + event (in which the column fields will not be set) to the user. + */ + virtual bool ItemChanged(const wxDataViewItem& item); + + /** + Call this to inform the model that an item has been deleted from the data. + */ + virtual bool ItemDeleted(const wxDataViewItem& parent, + const wxDataViewItem& item); + + /** + Call this to inform the model that several items have been added + to the data. + */ + virtual bool ItemsAdded(const wxDataViewItem& parent, + const wxDataViewItemArray& items); + + /** + Call this to inform the model that several items have changed. + + This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + events (in which the column fields will not be set) to the user. + */ + virtual bool ItemsChanged(const wxDataViewItemArray& items); + + /** + Call this to inform the model that several items have been deleted. + */ + virtual bool ItemsDeleted(const wxDataViewItem& parent, + const wxDataViewItemArray& items); + + /** + Remove the @e notifier from the list of notifiers. + */ + void RemoveNotifier(wxDataViewModelNotifier* notifier); + + /** + Call this to initiate a resort after the sort function has + been changed. + */ + virtual void Resort(); + + /** + This gets called in order to set a value in the data model. + The most common scenario is that the wxDataViewCtrl calls + this method after the user changed some data in the view. + Afterwards ValueChanged() + has to be called! + */ + virtual bool SetValue(const wxVariant& variant, + const wxDataViewItem& item, + unsigned int col); + + /** + Call this to inform this model that a value in the model has + been changed. This is also called from wxDataViewCtrl's + internal editing code, e.g. when editing a text field + in the control. + + This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + event to the user. + */ + virtual bool ValueChanged(const wxDataViewItem& item, + unsigned int col); +}; + + +/** + @class wxDataViewCustomRenderer + @wxheader{dataview.h} + + You need to derive a new class from wxDataViewCustomRenderer in + order to write a new renderer. You need to override at least + wxDataViewRenderer::SetValue, + wxDataViewRenderer::GetValue, + wxDataViewCustomRenderer::GetSize + and wxDataViewCustomRenderer::Render. + + If you want your renderer to support in-place editing then you + also need to override + wxDataViewCustomRenderer::HasEditorCtrl, + wxDataViewCustomRenderer::CreateEditorCtrl + and wxDataViewCustomRenderer::GetValueFromEditorCtrl. + Note that a special event handler will be pushed onto that + editor control which handles ENTER and focus out events + in order to end the editing. + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewCustomRenderer : public wxDataViewRenderer +{ +public: + /** + Constructor. + */ + wxDataViewCustomRenderer(const wxString& varianttype = "string", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + bool no_init = @false); + + /** + Destructor. + */ + ~wxDataViewCustomRenderer(); + + /** + Override this to react to double clicks or ENTER. + */ + virtual bool Activate(wxRect cell, wxDataViewModel* model, + unsigned int col, + unsigned int row); + + /** + Override this to create the actual editor control once editing + is about to start. @e parent is the parent of the editor + control, @e labelRect indicates the position and + size of the editor control and @e value is its initial value: + */ + virtual wxControl* CreateEditorCtrl(wxWindow * parent, + wxRect labelRect, + const wxVariant & value); + + /** + Create DC on request. Internal. + */ +#define virtual wxDC* GetDC() /* implementation is private */ + + /** + Return size required to show content. + */ + virtual wxSize GetSize(); + + /** + Overrride this so that the renderer can get the value + from the editor control (pointed to by @e editor): + */ + virtual bool GetValueFromEditorCtrl(wxControl* editor, + wxVariant & value); + + /** + Override this and make it return @e @true in order to + indicate that this renderer supports in-place editing. + */ + virtual bool HasEditorCtrl(); + + /** + Overrride this to react to a left click. + */ + virtual bool LeftClick(wxPoint cursor, wxRect cell, + wxDataViewModel* model, + unsigned int col, + unsigned int row); + + /** + Override this to render the cell. Before this is called, + wxDataViewRenderer::SetValue was called + so that this instance knows what to render. + */ + virtual bool Render(wxRect cell, wxDC* dc, int state); + + /** + This method should be called from within Render() + whenever you need to render simple text. This will ensure that the + correct colour, font and vertical alignment will be chosen so the + text will look the same as text drawn by native renderers. + */ + bool RenderText(const wxString& text, int xoffset, wxRect cell, + wxDC* dc, int state); + + /** + Overrride this to react to a right click. + */ + virtual bool RightClick(wxPoint cursor, wxRect cell, + wxDataViewModel* model, + unsigned int col, + unsigned int row); + + /** + Overrride this to start a drag operation. + */ + virtual bool StartDrag(wxPoint cursor, wxRect cell, + wxDataViewModel* model, + unsigned int col, + unsigned int row); +}; + + +/** + @class wxDataViewBitmapRenderer + @wxheader{dataview.h} + + wxDataViewBitmapRenderer + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewBitmapRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT); +}; + + +/** + @class wxDataViewItemAttr + @wxheader{dataview.h} + + This class is used to indicate to a wxDataViewCtrl + that a certain Item has extra font attributes + for its renderer. For this, it is required to override + wxDataViewModel::GetAttr. + + Attributes are currently only supported by + wxDataViewTextRendererText. + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewItemAttr +{ +public: + /** + Constructor. + */ + wxDataViewItemAttr(); + + /** + Call this to indicate that the item shall be displayed in bold text. + */ + void SetBold(bool set); + + /** + Call this to indicate that the item shall be displayed with + that colour. + */ + void SetColour(const wxColour& colour); + + /** + Call this to indicate that the item shall be displayed in italic text. + */ + void SetItalic(bool set); +}; + + +/** + @class wxDataViewItem + @wxheader{dataview.h} + + wxDataViewItem is a small opaque class that represents an + item in a wxDataViewCtrl in a + persistent way, i.e. indepent of the position of the + item in the control or changes to its contents. It must + hold a unique ID of type @e void* in its only field + and can be converted to a from it. + + If the ID is @e @NULL the wxDataViewItem is invalid and + wxDataViewItem::IsOk will return @e @false + which used in many places in the API of wxDataViewCtrl + to indicate that e.g. no item was found. An ID of @NULL + is also used to indicate the invisible root. Examples + for this are + wxDataViewModel::GetParent and + wxDataViewModel::GetChildren. + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewItem +{ +public: + //@{ + /** + + */ + wxDataViewItem(void* id = @NULL); + wxDataViewItem(const wxDataViewItem& item); + //@} + + /** + Returns the ID. + */ +#define void* GetID() /* implementation is private */ + + /** + Returns @true if the ID is not @e @NULL. + */ +#define bool IsOk() /* implementation is private */ +}; + + +/** + @class wxDataViewCtrl + @wxheader{dataview.h} + + wxDataViewCtrl is a control to display data either + in a tree like fashion or in a tabular form or both. + If you only need to display a simple tree structure + with an API more like the older wxTreeCtrl class, + then the specialized wxDataViewTreeCtrl + can be used. + + A wxDataViewItem is used + to represent a (visible) item in the control. + + Unlike wxListCtrl wxDataViewCtrl doesn't + get its data from the user through virtual functions or by + setting it directly. Instead you need to write your own + wxDataViewModel and associate + it with this control. Then you need to add a number of + wxDataViewColumn to this control to + define what each column shall display. Each wxDataViewColumn + in turn owns 1 instance of a + wxDataViewRenderer to render its + cells. A number of standard renderers for rendering text, dates, + images, toggle, a progress bar etc. are provided. Additionally, + the user can write custom renderes deriving from + wxDataViewCustomRenderer + for displaying anything. + + All data transfer from the control to the model and the user + code is done through wxVariant which can + be extended to support more data formats as necessary. + Accordingly, all type information uses the strings returned + from wxVariant::GetType. + + @beginStyleTable + @style{wxDV_SINGLE}: + Single selection mode. This is the default. + @style{wxDV_MULTIPLE}: + Multiple selection mode. + @style{wxDV_ROW_LINES}: + Use alternating colours for rows if supported by platform and theme. + @style{wxDV_HORIZ_RULES}: + Display fine rules between row if supported. + @style{wxDV_VERT_RULES}: + Display fine rules between columns is supported. + @endStyleTable + + @library{wxadv} + @category{ctrl} + @appearance{dataviewctrl.png} +*/ +class wxDataViewCtrl : public wxControl +{ +public: + //@{ + /** + Constructor. Calls Create(). + */ + wxDataViewCtrl(); + wxDataViewCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator); + //@} + + /** + Destructor. + */ + ~wxDataViewCtrl(); + + //@{ + /** + Appends a column for rendering a bitmap. Returns the wxDataViewColumn + created in the function or @NULL on failure. + */ + wxDataViewColumn* AppendBitmapColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + /** + Add a wxDataViewColumn to the control. Returns + @e @true on success. + + Note that there is a number of short cut methods which implicitly create + a wxDataViewColumn and a + wxDataViewRenderer for it (see below). + */ + virtual bool AppendColumn(wxDataViewColumn* col); + + //@{ + /** + Appends a column for rendering a date. Returns the wxDataViewColumn + created in the function or @NULL on failure. + */ + wxDataViewColumn* AppendDateColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int width = -1, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendDateColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int width = -1, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering text with an icon. Returns the wxDataViewColumn + created in the function or @NULL on failure. This uses the + wxDataViewIconTextRenderer. + */ + wxDataViewColumn* AppendIconTextColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering a progress indicator. Returns the + wxDataViewColumn + created in the function or @NULL on failure. + */ + wxDataViewColumn* AppendProgressColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = 80, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendProgressColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = 80, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering text. Returns the wxDataViewColumn + created in the function or @NULL on failure. + */ + wxDataViewColumn* AppendTextColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendTextColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering a toggle. Returns the wxDataViewColumn + created in the function or @NULL on failure. + */ + wxDataViewColumn* AppendToggleColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = 30, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendToggleColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = 30, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + /** + Associates a wxDataViewModel with the + control. This increases the reference count of the model by 1. + */ + virtual bool AssociateModel(wxDataViewModel* model); + + /** + Removes all columns. + */ + virtual bool ClearColumns(); + + /** + Unselects all rows. + */ + void ClearSelection(); + + /** + Collapses the item. + */ + void Collapse(const wxDataViewItem & item); + + /** + Create the control. Useful for two step creation. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator); + + /** + Deletes given column. + */ + virtual bool DeleteColumn(const wxDataViewColumn* column); + + /** + Call this to ensure that the given item is visible. + */ + void EnsureVisible(const wxDataViewItem & item, + const wxDataViewColumn* column = @NULL); + + /** + Expands the item. + */ + void Expand(const wxDataViewItem & item); + + /** + Returns pointer to the column. @e pos refers to the + position in the control which may change after reordering + columns by the user. + */ + virtual wxDataViewColumn* GetColumn(unsigned int pos); + + /** + Returns the number of columns. + */ + virtual unsigned int GetColumnCount(); + + /** + Returns the position of the column or -1 if not found in the control. + */ + virtual int GetColumnPosition(const wxDataViewColumn* column); + + /** + Returns column containing the expanders. + */ + wxDataViewColumn * GetExpanderColumn(); + + /** + Returns indentation. + */ + int GetIndent(); + + /** + Returns item rect. + */ + wxRect GetItemRect(const wxDataViewItem& item, + const wxDataViewColumn * col = @NULL); + + /** + Returns pointer to the data model associated with the + control (if any). + */ + virtual wxDataViewModel* GetModel(); + + /** + Returns first selected item or an invalid item if none is selected. + */ + wxDataViewItem GetSelection(); + + /** + Fills @e sel with currently selected items and returns + their number. + */ + int GetSelections(wxDataViewItemArray & sel); + + /** + Returns the wxDataViewColumn currently responsible for sorting + or @NULL if none has been selected. + */ + virtual wxDataViewColumn* GetSortingColumn(); + + /** + Hittest. + */ + void HitTest(const wxPoint& point, wxDataViewItem& item, + wxDataViewColumn *& col); + + /** + Return @true if the item is selected. + */ + bool IsSelected(const wxDataViewItem & item); + + /** + Select the given item. + */ + void Select(const wxDataViewItem & item); + + /** + Select all items. + */ + void SelectAll(); + + /** + Set which column shall contain the tree-like expanders. + */ + void SetExpanderColumn(wxDataViewColumn * col); + + /** + Sets the indendation. + */ + void SetIndent(int indent); + + /** + Sets the selection to the array of wxDataViewItems. + */ + void SetSelections(const wxDataViewItemArray & sel); + + /** + Unselect the given item. + */ + void Unselect(const wxDataViewItem & item); + + /** + Unselect all item. This method only has effect if multiple + selections are allowed. + */ + void UnselectAll(); +}; + + +/** + @class wxDataViewModelNotifier + @wxheader{dataview.h} + + A wxDataViewModelNotifier instance is owned by a + wxDataViewModel + and mirrors its notification interface. See + the documentation of that class for further + information. + + @library{wxbase} + @category{FIXME} +*/ +class wxDataViewModelNotifier +{ +public: + /** + Constructor. + */ + wxDataViewModelNotifier(); + + /** + Destructor. + */ + ~wxDataViewModelNotifier(); + + /** + Called by owning model. + */ + bool Cleared(); + + /** + Get owning wxDataViewModel. + */ + wxDataViewModel* GetOwner(); + + /** + Called by owning model. + */ + bool ItemAdded(const wxDataViewItem& parent, + const wxDataViewItem& item); + + /** + Called by owning model. + */ + bool ItemChanged(const wxDataViewItem& item); + + /** + Called by owning model. + */ + bool ItemDeleted(const wxDataViewItem& parent, + const wxDataViewItem& item); + + /** + Called by owning model. + */ + bool ItemsAdded(const wxDataViewItem& parent, + const wxDataViewItemArray& items); + + /** + Called by owning model. + */ + bool ItemsChanged(const wxDataViewItemArray& items); + + /** + Called by owning model. + */ + bool ItemsDeleted(const wxDataViewItem& parent, + const wxDataViewItemArray& items); + + /** + Called by owning model. + */ + void Resort(); + + /** + Set owner of this notifier. Used internally. + */ + void SetOwner(wxDataViewModel* owner); + + /** + Called by owning model. + */ + bool ValueChanged(const wxDataViewItem& item, unsigned int col); +}; + + +/** + @class wxDataViewRenderer + @wxheader{dataview.h} + + This class is used by wxDataViewCtrl to + render the individual cells. One instance of a renderer class is + owned by wxDataViewColumn. There is + a number of ready-to-use renderers provided: + wxDataViewTextRenderer, + wxDataViewTextRendererAttr, + wxDataViewIconTextRenderer, + wxDataViewToggleRenderer, + wxDataViewProgressRenderer, + wxDataViewBitmapRenderer, + wxDataViewDateRenderer. + wxDataViewSpinRenderer. + + Additionally, the user can write own renderers by deriving from + wxDataViewCustomRenderer. + + The @e wxDataViewCellMode flag controls, what actions + the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE + indicates that the user can double click the cell and + something will happen (e.g. a window for editing a date + will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates + that the user can edit the data in-place, i.e. an control + will show up after a slow click on the cell. This behaviour + is best known from changing the filename in most file + managers etc. + + + @code + enum wxDataViewCellMode + { + wxDATAVIEW_CELL_INERT, + wxDATAVIEW_CELL_ACTIVATABLE, + wxDATAVIEW_CELL_EDITABLE + }; + @endcode + + The @e wxDataViewCellRenderState flag controls how the + the renderer should display its contents in a cell: + + @code + enum wxDataViewCellRenderState + { + wxDATAVIEW_CELL_SELECTED = 1, + wxDATAVIEW_CELL_PRELIT = 2, + wxDATAVIEW_CELL_INSENSITIVE = 4, + wxDATAVIEW_CELL_FOCUSED = 8 + }; + @endcode + + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewRenderer : public wxObject +{ +public: + /** + Constructor. + */ + wxDataViewRenderer(const wxString& varianttype, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int alignment = wxALIGN_LEFT|wxALIGN_CENTRE_VERTICAL); + + /** + Returns the cell mode. + */ + virtual wxDataViewCellMode GetMode(); + + /** + Returns pointer to the owning wxDataViewColumn. + */ + virtual wxDataViewColumn* GetOwner(); + + /** + This methods retrieves the value from the renderer in order to + transfer the value back to the data model. Returns @e @false + on failure. + */ + virtual bool GetValue(wxVariant& value); + + /** + Returns a string with the type of the wxVariant + supported by this renderer. + */ + virtual wxString GetVariantType(); + + /** + Sets the owning wxDataViewColumn. This + is usually called from within wxDataViewColumn. + */ + virtual void SetOwner(wxDataViewColumn* owner); + + /** + Set the value of the renderer (and thus its cell) to @e value. + The internal code will then render this cell with this data. + */ + virtual bool SetValue(const wxVariant& value); + + /** + Before data is committed to the data model, it is passed to this + method where it can be checked for validity. This can also be + used for checking a valid range or limiting the user input in + a certain aspect (e.g. max number of characters or only alphanumeric + input, ASCII only etc.). Return @e @false if the value is + not valid. + + Please note that due to implementation limitations, this validation + is done after the editing control already is destroyed and the + editing process finished. + */ + virtual bool Validate(wxVariant& value); +}; + + +/** + @class wxDataViewTextRenderer + @wxheader{dataview.h} + + wxDataViewTextRenderer is used for rendering text. It supports + in-place editing if desired. + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewTextRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewTextRenderer(const wxString& varianttype = "string", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT); +}; + + +/** + @class wxDataViewProgressRenderer + @wxheader{dataview.h} + + wxDataViewProgressRenderer + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewProgressRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewProgressRenderer(const wxString& label = wxEmptyString, + const wxString& varianttype = "long", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT); +}; + + +/** + @class wxDataViewSpinRenderer + @wxheader{dataview.h} + + This is a specialized renderer for rendering integer values. It + supports modifying the values in-place by using a wxSpinCtrl. + The renderer only support variants of type @e long. + + @library{wxbase} + @category{FIXME} +*/ +class wxDataViewSpinRenderer : public wxDataViewCustomRenderer +{ +public: + /** + Constructor. @e min and @e max indicate the minimum und + maximum values of for the wxSpinCtrl. + */ + wxDataViewSpinRenderer(int min, int max, + wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, + int alignment = wxDVR_DEFAULT_ALIGNMENT); +}; + + +/** + @class wxDataViewToggleRenderer + @wxheader{dataview.h} + + wxDataViewToggleRenderer + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewToggleRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewToggleRenderer(const wxString& varianttype = "bool", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT); +}; + + +/** + @class wxDataViewTreeCtrl + @wxheader{dataview.h} + + This class is a wxDataViewCtrl which internally + uses a wxDataViewTreeStore and forwards + most of its API to that class. Additionally, it uses a wxImageList + to store a list of icons. The main purpose of this class is to look + like a wxTreeCtrl to make a transition from it + to the wxDataViewCtrl class simpler. + + @library{wxbase} + @category{ctrl} + @appearance{dataviewtreectrl.png} +*/ +class wxDataViewTreeCtrl : public wxDataViewCtrl +{ +public: + //@{ + /** + Constructor. Calls Create(). + */ + wxDataViewTreeCtrl(); + wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDV_NO_HEADER, + const wxValidator& validator = wxDefaultValidator); + //@} + + /** + Destructor. Deletes the image list if any. + */ + ~wxDataViewTreeCtrl(); + + /** + + */ + wxDataViewItem AppendContainer(const wxDataViewItem& parent, + const wxString& text, + int icon = -1, + int expanded = -1, + wxClientData* data = @NULL); + + /** + + */ + wxDataViewItem AppendItem(const wxDataViewItem& parent, + const wxString& text, + int icon = -1, + wxClientData* data = @NULL); + + /** + Creates the control and a wxDataViewTreeStore as + its internal model. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDV_NO_HEADER, + const wxValidator& validator = wxDefaultValidator); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void DeleteAllItems(); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void DeleteChildren(const wxDataViewItem& item); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void DeleteItem(const wxDataViewItem& item); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + int GetChildCount(const wxDataViewItem& parent); + + /** + Returns the image list. + */ + wxImageList* GetImageList(); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + wxClientData* GetItemData(const wxDataViewItem& item); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + const wxIcon GetItemExpandedIcon(const wxDataViewItem& item); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + const wxIcon GetItemIcon(const wxDataViewItem& item); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + wxString GetItemText(const wxDataViewItem& item); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + wxDataViewItem GetNthChild(const wxDataViewItem& parent, + unsigned int pos); + + //@{ + /** + Returns the store. + */ + wxDataViewTreeStore* GetStore(); + const wxDataViewTreeStore* GetStore(); + //@} + + /** + Calls the same method from wxDataViewTreeStore but uess + and index position in the image list instead of a wxIcon. + */ + wxDataViewItem InsertContainer(const wxDataViewItem& parent, + const wxDataViewItem& previous, + const wxString& text, + int icon = -1, + int expanded = -1, + wxClientData* data = @NULL); + + /** + Calls the same method from wxDataViewTreeStore but uess + and index position in the image list instead of a wxIcon. + */ + wxDataViewItem InsertItem(const wxDataViewItem& parent, + const wxDataViewItem& previous, + const wxString& text, + int icon = -1, + wxClientData* data = @NULL); + + /** + Calls the same method from wxDataViewTreeStore but uess + and index position in the image list instead of a wxIcon. + */ + wxDataViewItem PrependContainer(const wxDataViewItem& parent, + const wxString& text, + int icon = -1, + int expanded = -1, + wxClientData* data = @NULL); + + /** + Calls the same method from wxDataViewTreeStore but uess + and index position in the image list instead of a wxIcon. + */ + wxDataViewItem PrependItem(const wxDataViewItem& parent, + const wxString& text, + int icon = -1, + wxClientData* data = @NULL); + + /** + Sets the image list. + */ + void SetImageList(wxImageList* imagelist); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void SetItemData(const wxDataViewItem& item, wxClientData* data); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void SetItemExpandedIcon(const wxDataViewItem& item, + const wxIcon& icon); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void SetItemText(const wxDataViewItem& item, + const wxString& text); +}; + + +/** + @class wxDataViewTreeStore + @wxheader{dataview.h} + + wxDataViewTreeStore is a specialised wxDataViewModel + for displaying simple trees very much like wxTreeCtrl + does and it offers a similar API. This class actually stores the entire + tree (therefore its name) and implements all virtual methods from the base + class so it can be used directly without having to derive any class from it. + This comes at the price of much reduced flexibility. + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewTreeStore : public wxDataViewModel +{ +public: + /** + Constructor. Creates the invisible root node internally. + */ + wxDataViewTreeStore(); + + /** + Destructor. + */ + ~wxDataViewTreeStore(); + + /** + Append a container. + */ + wxDataViewItem AppendContainer(const wxDataViewItem& parent, + const wxString& text, + const wxIcon& icon = wxNullIcon, + const wxIcon& expanded = wxNullIcon, + wxClientData* data = @NULL); + + /** + Append an item. + */ + wxDataViewItem AppendItem(const wxDataViewItem& parent, + const wxString& text, + const wxIcon& icon = wxNullIcon, + wxClientData* data = @NULL); + + /** + Delete all item in the model. + */ + void DeleteAllItems(); + + /** + Delete all children of the item, but not the item itself. + */ + void DeleteChildren(const wxDataViewItem& item); + + /** + Delete this item. + */ + void DeleteItem(const wxDataViewItem& item); + + /** + Return the number of children of item. + */ + int GetChildCount(const wxDataViewItem& parent); + + /** + Returns the client data asoociated with the item. + */ + wxClientData* GetItemData(const wxDataViewItem& item); + + /** + Returns the icon to display in expanded containers. + */ + const wxIcon GetItemExpandedIcon(const wxDataViewItem& item); + + /** + Returns the icon of the item. + */ + const wxIcon GetItemIcon(const wxDataViewItem& item); + + /** + Returns the text of the item. + */ + wxString GetItemText(const wxDataViewItem& item); + + /** + Returns the nth child item of item. + */ + wxDataViewItem GetNthChild(const wxDataViewItem& parent, + unsigned int pos); + + /** + Inserts a container after @e previous. + */ + wxDataViewItem InsertContainer(const wxDataViewItem& parent, + const wxDataViewItem& previous, + const wxString& text, + const wxIcon& icon = wxNullIcon, + const wxIcon& expanded = wxNullIcon, + wxClientData* data = @NULL); + + /** + Inserts an item after @e previous. + */ + wxDataViewItem InsertItem(const wxDataViewItem& parent, + const wxDataViewItem& previous, + const wxString& text, + const wxIcon& icon = wxNullIcon, + wxClientData* data = @NULL); + + /** + Inserts a container before the first child item or @e parent. + */ + wxDataViewItem PrependContainer(const wxDataViewItem& parent, + const wxString& text, + const wxIcon& icon = wxNullIcon, + const wxIcon& expanded = wxNullIcon, + wxClientData* data = @NULL); + + /** + Inserts an item before the first child item or @e parent. + */ + wxDataViewItem PrependItem(const wxDataViewItem& parent, + const wxString& text, + const wxIcon& icon = wxNullIcon, + wxClientData* data = @NULL); + + /** + Sets the client data associated with the item. + */ + void SetItemData(const wxDataViewItem& item, wxClientData* data); + + /** + Sets the expanded icon for the item. + */ + void SetItemExpandedIcon(const wxDataViewItem& item, + const wxIcon& icon); + + /** + Sets the icon for the item. + */ + void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); +}; + + +/** + @class wxDataViewDateRenderer + @wxheader{dataview.h} + + wxDataViewDateRenderer + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewDateRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewDateRenderer(const wxString& varianttype = "datetime", + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE); +}; + + +/** + @class wxDataViewTextRendererAttr + @wxheader{dataview.h} + + The same as wxDataViewTextRenderer but with + support for font attributes. Font attributes are currently only supported + under GTK+ and MSW. + + See also wxDataViewModel::GetAttr and + wxDataViewItemAttr. + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewTextRendererAttr : public wxDataViewTextRenderer +{ +public: + /** + + */ + wxDataViewTextRendererAttr(const wxString& varianttype = "string", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT); +}; + + +/** + @class wxDataViewColumn + @wxheader{dataview.h} + + This class represents a column in a wxDataViewCtrl. + One wxDataViewColumn is bound to one column in the data model, + to which the wxDataViewCtrl has been associated. + + An instance of wxDataViewRenderer is used by + this class to render its data. + + @library{wxadv} + @category{FIXME} +*/ +class wxDataViewColumn : public wxObject +{ +public: + //@{ + /** + Constructors. + */ + wxDataViewColumn(const wxString& title, + wxDataViewRenderer* renderer, + unsigned int model_column, + int width = wxDVC_DEFAULT_WIDTH, + wxAlignment align = wxALIGN_CENTRE, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn(const wxBitmap& bitmap, + wxDataViewRenderer* renderer, + unsigned int model_column, + int width = wxDVC_DEFAULT_WIDTH, + wxAlignment align = wxALIGN_CENTRE, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + /** + Destructor. + */ + ~wxDataViewColumn(); + + /** + Returns the bitmap in the header of the column, if any. + */ + const wxBitmap GetBitmap(); + + /** + Returns the index of the column of the model, which this + wxDataViewColumn is displaying. + */ + unsigned int GetModelColumn(); + + /** + Returns the owning wxDataViewCtrl. + */ + wxDataViewCtrl* GetOwner(); + + /** + Returns the renderer of this wxDataViewColumn. + + See also wxDataViewRenderer. + */ + wxDataViewRenderer* GetRenderer(); + + /** + Returns @true if the column is reorderable. + */ + bool GetReorderable(); + + /** + Returns @true if the column is sortable. + + See SetSortable() + */ + bool GetSortable(); + + /** + Returns the width of the column. + */ + int GetWidth(); + + /** + Returns @true, if the sort order is ascending. + + See also SetSortOrder() + */ + bool IsSortOrderAscending(); + + /** + Set the alignment of the column header. + */ + void SetAlignment(wxAlignment align); + + /** + Set the bitmap of the column header. + */ + void SetBitmap(const wxBitmap& bitmap); + + /** + Indicate wether the column can be reordered by the + user using the mouse. This is typically implemented + visually by dragging the header button around. + */ + void SetReorderable(bool reorderable); + + /** + Indicate the sort order if the implementation of the + wxDataViewCtrl supports it, most commonly by showing + a little arrow. + */ + void SetSortOrder(bool ascending); + + /** + Indicate that the column is sortable. This does + not show any sorting indicate yet, but it does + make the column header clickable. Call + SetSortOrder() + afterwards to actually make the sort indicator appear. + If @e sortable is @false, the column header is + no longer clickable and the sort indicator (little + arrow) will disappear. + */ + void SetSortable(bool sortable); + + /** + Set the title of the column header to @e title. + */ + void SetTitle(const wxString& title); +}; diff --git a/interface/datectrl.h b/interface/datectrl.h new file mode 100644 index 0000000000..4e54355667 --- /dev/null +++ b/interface/datectrl.h @@ -0,0 +1,166 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: datectrl.h +// Purpose: documentation for wxDatePickerCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDatePickerCtrl + @wxheader{datectrl.h} + + This control allows the user to select a date. Unlike + wxCalendarCtrl, which is a relatively big control, + wxDatePickerCtrl is implemented as a small window showing the currently + selected date. + The control can be edited using the keyboard, and can also display a popup + window for more user-friendly date selection, depending on the styles used and + the platform, except PalmOS where date is selected using native dialog. + + It is only available if @c wxUSE_DATEPICKCTRL is set to 1. + + @beginStyleTable + @style{wxDP_SPIN}: + Creates a control without a month calendar drop down but with + spin-control-like arrows to change individual date components. This + style is not supported by the generic version. + @style{wxDP_DROPDOWN}: + Creates a control with a month calendar drop-down part from which + the user can select a date. + @style{wxDP_DEFAULT}: + Creates a control with the style that is best supported for the + current platform (currently wxDP_SPIN under Windows and + wxDP_DROPDOWN elsewhere). + @style{wxDP_ALLOWNONE}: + With this style, the control allows the user to not enter any valid + date at all. Without it - the default - the control always has some + valid date. + @style{wxDP_SHOWCENTURY}: + Forces display of the century in the default date format. Without + this style the century could be displayed, or not, depending on the + default date representation in the system. + @endStyleTable + + @beginEventTable + @event{EVT_DATE_CHANGED(id\, func)}: + This event fires when the user changes the current selection in the + control. + @endEventTable + + @library{wxadv} + @category{miscpickers} + @appearance{datepickerctrl.png} + + @seealso + wxCalendarCtrl, wxDateEvent +*/ +class wxDatePickerCtrl : public wxControl +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxDatePickerCtrl(wxWindow * parent, wxWindowID id, + const wxDateTime& dt = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDP_DEFAULT | wxDP_SHOWCENTURY, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "datectrl"); + + /** + @param parent + Parent window, must not be non-@NULL. + + @param id + The identifier for the control. + + @param dt + The initial value of the control, if an invalid date (such as the + default value) is used, the control is set to today. + + @param pos + Initial position. + + @param size + Initial size. If left at default value, the control chooses its + own best size by using the height approximately equal to a text control and + width large enough to show the date string fully. + + @param style + The window style, should be left at 0 as there are no + special styles for this control in this version. + + @param validator + Validator which can be used for additional date checks. + + @param name + Control name. + + @returns @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow * parent, wxWindowID id, + const wxDateTime& dt = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDP_DEFAULT | wxDP_SHOWCENTURY, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "datectrl"); + + /** + If the control had been previously limited to a range of dates using + SetRange(), returns the lower and upper + bounds of this range. If no range is set (or only one of the bounds is set), + @e dt1 and/or @e dt2 are set to be invalid. + + @param dt1 + Pointer to the object which receives the lower range limit or + becomes invalid if it is not set. May be @NULL if the caller is not + interested in lower limit + + @param dt2 + Same as above but for the upper limit + + @returns @false if no range limits are currently set, @true if at least one + bound is set. + */ + bool GetRange(wxDateTime * dt1, wxDateTime dt2); + + /** + Returns the currently selected. If there is no selection or the selection is + outside of the current range, an invalid object is returned. + */ + wxDateTime GetValue(); + + /** + Please note that this function is only available in the generic version of this + control. The native version always uses the current system locale. + + Sets the display format for the date in the control. See wxDateTime for the + meaning of format strings. + + @remarks If the format parameter is invalid, the behaviour is undefined. + */ + void SetFormat(const wxChar* format); + + /** + Sets the valid range for the date selection. If @e dt1 is valid, it becomes + the earliest date (inclusive) accepted by the control. If @e dt2 is valid, + it becomes the latest possible date. + + @remarks If the current value of the control is outside of the newly set + range bounds, the behaviour is undefined. + */ + void SetRange(const wxDateTime& dt1, const wxDateTime& dt2); + + /** + Changes the current value of the control. The date should be valid and included + in the currently selected range, if any. + + Calling this method does not result in a date change event. + */ + void SetValue(const wxDateTime& dt); +}; diff --git a/interface/dateevt.h b/interface/dateevt.h new file mode 100644 index 0000000000..2273f7c6fc --- /dev/null +++ b/interface/dateevt.h @@ -0,0 +1,33 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dateevt.h +// Purpose: documentation for wxDateEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDateEvent + @wxheader{dateevt.h} + + This event class holds information about a date change and is used together + with wxDatePickerCtrl. It also serves as a base class + for wxCalendarEvent. + + @library{wxadv} + @category{events} +*/ +class wxDateEvent : public wxCommandEvent +{ +public: + /** + Returns the date. + */ + const wxDateTime GetDate(); + + /** + Sets the date carried by the event, normally only used by the library + internally. + */ + void SetDate(const wxDateTime& date); +}; diff --git a/interface/datetime.h b/interface/datetime.h new file mode 100644 index 0000000000..fb99b19f9d --- /dev/null +++ b/interface/datetime.h @@ -0,0 +1,1797 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: datetime.h +// Purpose: documentation for wxDateTime class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDateTime + @wxheader{datetime.h} + + wxDateTime class represents an absolute moment in the time. + + @library{wxbase} + @category{data} + + @seealso + @ref overview_wxdatetimeoverview "Date classes overview", wxTimeSpan, + wxDateSpan, wxCalendarCtrl +*/ +class wxDateTime +{ +public: + /** + Same as @ref setdate() Set + */ + wxDateTime(wxDateTime_t day, Month month = Inv_Month, + int Inv_Year, wxDateTime_t hour = 0, + wxDateTime_t minute = 0, + wxDateTime_t second = 0, + wxDateTime_t millisec = 0); + + /** + Here are the trivial accessors. Other functions, which might have to perform + some more complicated calculations to find the answer are under the + @ref overview_datetimecalculations "Calendar calculations" section. + + IsValid() + + GetTicks() + + GetCentury() + + GetYear() + + GetMonth() + + GetDay() + + GetWeekDay() + + GetHour() + + GetMinute() + + GetSecond() + + GetMillisecond() + + GetDayOfYear() + + GetWeekOfYear() + + GetWeekOfMonth() + + GetYearDay() + + IsWorkDay() + + IsGregorianDate() + + GetAsDOS() + */ + + + //@{ + /** + Adds the given date span to this object. + */ + wxDateTime Add(const wxDateSpan& diff); + wxDateTime Add(const wxDateSpan& diff); + wxDateTime operator+=(const wxDateSpan& diff); + //@} + + /** + Some degree of support for the date units used in astronomy and/or history is + provided. You can construct a wxDateTime object from a + @ref setjdn() JDN and you may also get its JDN, + @ref getmodifiedjuliandaynumber() MJD or + @ref getratadie() "Rata Die number" from it. + + @ref wxdatetimejdn() "wxDateTime(double jdn)" + + @ref setjdn() "Set(double jdn)" + + GetJulianDayNumber() + + GetJDN() + + GetModifiedJulianDayNumber() + + GetMJD() + + GetRataDie() + */ + + + /** + The functions in this section perform the basic calendar calculations, mostly + related to the week days. They allow to find the given week day in the + week with given number (either in the month or in the year) and so on. + + All (non-const) functions in this section don't modify the time part of the + wxDateTime -- they only work with the date part of it. + + SetToWeekDayInSameWeek() + + GetWeekDayInSameWeek() + + SetToNextWeekDay() + + GetNextWeekDay() + + SetToPrevWeekDay() + + GetPrevWeekDay() + + SetToWeekDay() + + @ref wxDateTime::getweekday2 GetWeekDay + + SetToLastWeekDay() + + GetLastWeekDay() + + SetToWeekOfYear() + + SetToLastMonthDay() + + GetLastMonthDay() + + SetToYearDay() + + GetYearDay() + */ + + + /** + Constructors and various @c Set() methods are collected here. If you + construct a date object from separate values for day, month and year, you + should use IsValid() method to check that the + values were correct as constructors can not return an error code. + + @ref wxdatetimedef() wxDateTime + + @ref wxdatetimetimet() wxDateTime(time_t) + + @ref wxdatetimetm() "wxDateTime(struct tm)" + + @ref wxdatetimejdn() "wxDateTime(double jdn)" + + @ref wxdatetimetime() "wxDateTime(h, m, s, ms)" + + @ref wxdatetimedate() "wxDateTime(day, mon, year, h, m, s, ms)" + + SetToCurrent() + + @ref settimet() Set(time_t) + + @ref settm() "Set(struct tm)" + + @ref setjdn() "Set(double jdn)" + + @ref settime() "Set(h, m, s, ms)" + + @ref setdate() "Set(day, mon, year, h, m, s, ms)" + + @ref setfromdos() "SetFromDOS(unsigned long ddt)" + + ResetTime() + + SetYear() + + SetMonth() + + @ref setdate() SetDay + + SetHour() + + SetMinute() + + SetSecond() + + SetMillisecond() + + @ref operatoreqtimet() operator=(time_t) + + @ref operatoreqtm() "operator=(struct tm)" + */ + + + /** + 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: + */ + static int ConvertYearToBC(int year); + + /** + These functions carry out arithmetics on the wxDateTime + objects. As explained in the overview, either wxTimeSpan or wxDateSpan may be + added to wxDateTime, hence all functions are overloaded to accept both + arguments. + + Also, both @c Add() and @c Subtract() have both const and non-const + version. The first one returns a new object which represents the + sum/difference of the original one with the argument while the second form + modifies the object to which it is applied. The operators -= and += are + defined to be equivalent to the second forms of these functions. + + @ref addts() Add(wxTimeSpan) + + @ref addds() Add(wxDateSpan) + + @ref subtractts() Subtract(wxTimeSpan) + + @ref subtractds() Subtract(wxDateSpan) + + @ref subtractdt() Subtract(wxDateTime) + + @ref addts() oparator+=(wxTimeSpan) + + @ref addds() oparator+=(wxDateSpan) + + @ref subtractts() oparator-=(wxTimeSpan) + + @ref subtractds() oparator-=(wxDateSpan) + */ + + + /** + There are several function to allow date comparison. To supplement them, a few + global operators , etc taking wxDateTime are defined. + + IsEqualTo() + + IsEarlierThan() + + IsLaterThan() + + IsStrictlyBetween() + + IsBetween() + + IsSameDate() + + IsSameTime() + + IsEqualUpTo() + */ + + + /** + This function does the same as the standard ANSI C @c strftime(3) function. + Please see its description for the meaning of @e format parameter. + + It also accepts a few wxWidgets-specific extensions: you can optionally specify + the width of the field to follow using @c printf(3)-like syntax and the + format specification @c %l can be used to get the number of milliseconds. + + @sa ParseFormat() + */ + wxString Format(const wxChar * format = wxDefaultDateTimeFormat, + const TimeZone& tz = Local); + + /** + Identical to calling Format() with @c "%x" + argument (which means 'preferred date representation for the current locale'). + */ + wxString FormatDate(); + + /** + Returns the combined date-time representation in the ISO 8601 format + (YYYY-MM-DDTHH:MM:SS). The @e sep parameter default value produces the + result exactly corresponding to the ISO standard, but it can also be useful to + use a space as seprator if a more human-readable combined date-time + representation is needed. + + @sa FormatISODate(), FormatISOTime(), + ParseISOCombined() + */ + wxString FormatISOCombined(char sep = 'T'); + + /** + This function returns the date representation in the ISO 8601 format + (YYYY-MM-DD). + */ + wxString FormatISODate(); + + /** + This function returns the time representation in the ISO 8601 format + (HH:MM:SS). + */ + wxString FormatISOTime(); + + /** + Identical to calling Format() with @c "%X" + argument (which means 'preferred time representation for the current locale'). + */ + wxString FormatTime(); + + /** + Transform the date from the given time zone to the local one. If @e noDST is + @true, no DST adjustments will be made. + + Returns the date in the local time zone. + */ + wxDateTime FromTimezone(const TimeZone& tz, + bool noDST = @false); + + /** + Returns the translations of the strings @c AM and @c PM used for time + formatting for the current locale. Either of the pointers may be @NULL if + the corresponding value is not needed. + */ + static void GetAmPmStrings(wxString * am, wxString * pm); + + /** + Returns the date and time in + DOS + format. + */ + unsigned long GetAsDOS(); + + /** + Get the beginning of DST for the given country in the given year (current one + by default). This function suffers from limitations described in + @ref overview_tdatedst "DST overview". + + @sa GetEndDST() + */ + static wxDateTime GetBeginDST(int year = Inv_Year, + Country country = Country_Default); + + /** + Returns the century of this date. + */ + int GetCentury(const TimeZone& tz = Local); + + /** + Returns the current default country. The default country is used for DST + calculations, for example. + + @sa SetCountry() + */ + static Country GetCountry(); + + /** + Get the current month in given calendar (only Gregorian is currently supported). + */ + static Month GetCurrentMonth(Calendar cal = Gregorian); + + /** + Get the current year in given calendar (only Gregorian is currently supported). + */ + static int GetCurrentYear(Calendar cal = Gregorian); + + /** + Returns the object having the same date component as this one but time of + 00:00:00. + + This function is new since wxWidgets version 2.8.2 + + @sa ResetTime() + */ + wxDateTime GetDateOnly(); + + /** + Returns the day in the given timezone (local one by default). + */ + wxDateTime_t GetDay(const TimeZone& tz = Local); + + /** + Returns the day of the year (in 1...366 range) in the given timezone + (local one by default). + */ + wxDateTime_t GetDayOfYear(const TimeZone& tz = Local); + + /** + Returns the end of DST for the given country in the given year (current one by + default). + + @sa GetBeginDST() + */ + static wxDateTime GetEndDST(int year = Inv_Year, + Country country = Country_Default); + + /** + Returns the hour in the given timezone (local one by default). + */ + wxDateTime_t GetHour(const TimeZone& tz = Local); + + /** + Synonym for GetJulianDayNumber(). + */ +#define double GetJDN() /* implementation is private */ + + /** + Returns the @ref setjdn() JDN corresponding to this date. Beware + of rounding errors! + + @sa GetModifiedJulianDayNumber() + */ + double GetJulianDayNumber(); + + /** + Returns the copy of this object to which + SetToLastMonthDay() was applied. + */ + wxDateTime GetLastMonthDay(Month month = Inv_Month, + int year = Inv_Year); + + /** + Returns the copy of this object to which + SetToLastWeekDay() was applied. + */ + wxDateTime GetLastWeekDay(WeekDay weekday, + Month month = Inv_Month, + int year = Inv_Year); + + /** + Synonym for GetModifiedJulianDayNumber(). + */ +#define double GetMJD() /* implementation is private */ + + /** + Returns the milliseconds in the given timezone (local one by default). + */ + wxDateTime_t GetMillisecond(const TimeZone& tz = Local); + + /** + Returns the minute in the given timezone (local one by default). + */ + wxDateTime_t GetMinute(const TimeZone& tz = Local); + + /** + Returns the @e 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. + */ + double GetModifiedJulianDayNumber(); + + /** + Returns the month in the given timezone (local one by default). + */ + Month GetMonth(const TimeZone& tz = Local); + + /** + Gets the full (default) or abbreviated (specify @c Name_Abbr name of the + given month. + + @sa GetWeekDayName() + */ + static wxString GetMonthName(Month month, + NameFlags flags = Name_Full); + + /** + Returns the copy of this object to which + SetToNextWeekDay() was applied. + */ + wxDateTime GetNextWeekDay(WeekDay weekday); + + //@{ + /** + Returns the number of days in the given year or in the given month of the + year. + + The only supported value for @e cal parameter is currently @c Gregorian. + */ + static wxDateTime_t GetNumberOfDays(int year, + Calendar cal = Gregorian); + static wxDateTime_t GetNumberOfDays(Month month, + int year = Inv_Year, + Calendar cal = Gregorian); + //@} + + /** + Returns the copy of this object to which + SetToPrevWeekDay() was applied. + */ + wxDateTime GetPrevWeekDay(WeekDay weekday); + + /** + Return the @e Rata Die number of this date. + + By definition, the Rata Die number is a date specified as the number of days + relative to a base date of December 31 of the year 0. Thus January 1 of the + year 1 is Rata Die day 1. + */ + double GetRataDie(); + + /** + Returns the seconds in the given timezone (local one by default). + */ + wxDateTime_t GetSecond(const TimeZone& tz = Local); + + /** + Returns the number of seconds since Jan 1, 1970. An assert failure will occur + if the date is not in the range covered by @c time_t type. + */ + time_t GetTicks(); + + /** + Returns the current time. + */ + static time_t GetTimeNow(); + + /** + Returns broken down representation of the date and time. + */ + Tm GetTm(const TimeZone& tz = Local); + + /** + Returns the current time broken down. Note that this function returns a + pointer to a static buffer that's reused by calls to this function and + certain C library functions (e.g. localtime). If there is any chance your + code might be used in a multi-threaded application, you really should use + the flavour of function GetTmNow() + taking a parameter. + */ + static struct tm * GetTmNow(); + + /** + Returns the copy of this object to which + SetToWeekDay() was applied. + */ + wxDateTime GetWeekDay(WeekDay weekday, int n = 1, + Month month = Inv_Month, + int year = Inv_Year); + + /** + Returns the copy of this object to which + SetToWeekDayInSameWeek() was + applied. + */ + wxDateTime GetWeekDayInSameWeek(WeekDay weekday, + WeekFlags flags = Monday_First); + + /** + Gets the full (default) or abbreviated (specify @c Name_Abbr name of the + given week day. + + @sa GetMonthName() + */ + static wxString GetWeekDayName(WeekDay weekday, + NameFlags flags = Name_Full); + + /** + Returns the ordinal number of the week in the month (in 1...5 range). + + As GetWeekOfYear(), this function supports + both conventions for the week start. See the description of these + @ref overview_wxdatetime "week start" conventions. + */ + wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First, + const TimeZone& tz = Local); + + /** + Returns the number of the week of the year this date is in. The first week of + the year is, according to international standards, the one containing Jan 4 or, + equivalently, the first week which has Thursday in this year. Both of these + definitions are the same as saying that the first week of the year must contain + more than half of its days in this year. Accordingly, the week number will + always be in 1...53 range (52 for non-leap years). + + The function depends on the @ref overview_wxdatetime "week start" convention + specified by the @e flags argument but its results for + @c Sunday_First are not well-defined as the ISO definition quoted above + applies to the weeks starting on Monday only. + */ + wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First, + const TimeZone& tz = Local); + + /** + Returns the year in the given timezone (local one by default). + */ + int GetYear(const TimeZone& tz = Local); + + /** + Returns the copy of this object to which + SetToYearDay() was applied. + */ + wxDateTime GetYearDay(wxDateTime_t yday); + + /** + Returns @true if IsStrictlyBetween() + is @true or if the date is equal to one of the limit values. + + @sa IsStrictlyBetween() + */ + bool IsBetween(const wxDateTime& t1, const wxDateTime& t2); + + /** + Returns @true if the DST is applied for this date in the given country. + */ +#define int IsDST(Country country = Country_Default) /* implementation is private */ + + /** + Returns @true if DST was used n the given year (the current one by + default) in the given country. + */ + static bool IsDSTApplicable(int year = Inv_Year, + Country country = Country_Default); + + /** + Returns @true if this date precedes the given one. + */ + bool IsEarlierThan(const wxDateTime& datetime); + + /** + Returns @true if the two dates are strictly identical. + */ + bool IsEqualTo(const wxDateTime& datetime); + + /** + Returns @true if the date is equal to another one up to the given time + interval, i.e. if the absolute difference between the two dates is less than + this interval. + */ + bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts); + + /** + Returns @true if the given date is later than the date of adoption of the + Gregorian calendar in the given country (and hence the Gregorian calendar + calculations make sense for it). + */ + bool IsGregorianDate(GregorianAdoption country = Gr_Standard); + + /** + Returns @true if this date is later than the given one. + */ + bool IsLaterThan(const wxDateTime& datetime); + + /** + Returns @true if the @e year is a leap one in the specified calendar. + + This functions supports Gregorian and Julian calendars. + */ + static bool IsLeapYear(int year = Inv_Year, + Calendar cal = Gregorian); + + /** + Returns @true if the date is the same without comparing the time parts. + */ + bool IsSameDate(const wxDateTime& dt); + + /** + Returns @true if the time is the same (although dates may differ). + */ + bool IsSameTime(const wxDateTime& dt); + + /** + Returns @true if this date lies strictly between the two others, + + @sa IsBetween() + */ + bool IsStrictlyBetween(const wxDateTime& t1, + const wxDateTime& t2); + + /** + Returns @true if the object represents a valid time moment. + */ + bool IsValid(); + + /** + This function returns @true if the specified (or default) country is one + of Western European ones. It is used internally by wxDateTime to determine the + DST convention and date and time formatting rules. + */ + static bool IsWestEuropeanCountry(Country country = Country_Default); + + /** + Returns @true is this day is not a holiday in the given country. + */ + bool IsWorkDay(Country country = Country_Default); + + /** + Same as FromTimezone() but modifies the object + in place. + */ + wxDateTime MakeFromTimezone(const TimeZone& tz, + bool noDST = @false); + + /** + Modifies the object in place to represent the date in another time zone. If + @e noDST is @true, no DST adjustments will be made. + */ + wxDateTime MakeTimezone(const TimeZone& tz, + bool noDST = @false); + + /** + This is the same as calling MakeTimezone() with + the argument @c GMT0. + */ + wxDateTime MakeUTC(bool noDST = @false); + + /** + Returns the object corresponding to the current time. + + Example: + Note that this function is accurate up to second: + UNow() should be used for better precision + (but it is less efficient and might not be available on all platforms). + + @sa Today() + */ +#define static wxDateTime Now() /* implementation is private */ + + //@{ + /** + 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. + */ + const char * ParseDate(const wxString& date, + wxString::const_iterator * end = @NULL); + const char * ParseDate(const char * date); + const wchar_t * ParseDate(const wchar_t * date); + //@} + + //@{ + /** + Parses the string @e 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 wxDateTime::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. + */ + const char * ParseDateTime(const wxString& datetime, + wxString::const_iterator * end = @NULL); + const char * ParseDateTime(const char * datetime); + const wchar_t * ParseDateTime(const wchar_t * datetime); + //@} + + //@{ + /** + This function parses the string @e date according to the given + @e format. The system @c strptime(3) function is used whenever available, + but even if it is not, this function is still implemented, although support + for locale-dependent format specifiers such as @c "%c", @c "%x" or @c "%X" may + not be perfect and GNU extensions such as @c "%z" and @c "%Z" are + not implemented. This function does handle the month and weekday + names in the current locale on all platforms, however. + + Please see the description of the ANSI C function @c strftime(3) for the syntax + of the format string. + + The @e dateDef parameter is used to fill in the fields which could not be + determined from the format string. For example, if the format is @c "%d" (the + ay of the month), the month and the year are taken from @e 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. + */ + const char * ParseFormat(const wxString& date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime, + wxString::const_iterator * end = @NULL); + const char * ParseFormat(const char * date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); + const wchar_t * ParseFormat(const wchar_t * date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); + //@} + + /** + This function parses the string containing the date and time in ISO 8601 + combined format (YYYY-MM-DDTHH:MM:SS). The separator between the date and time + parts must be equal to @e sep for the function to succeed. + + Returns @true if the entire string was parsed successfully, @false + otherwise. + */ + bool ParseISOCombined(const wxString& date, char sep = 'T'); + + /** + This function parses the date in ISO 8601 format (YYYY-MM-DD). + + Returns @true if the entire string was parsed successfully, @false + otherwise. + */ + bool ParseISODate(const wxString& date); + + /** + This function parses the time in ISO 8601 format (HH:MM:SS). + + Returns @true if the entire string was parsed successfully, @false + otherwise. + */ + bool ParseISOTime(const wxString& date); + + //@{ + /** + Parses the string @e date looking for a date formatted according to the RFC + 822 in it. The exact description of this format may, of course, be found in + the RFC (section 5), but, briefly, this is the format used in the headers of + Internet email messages and one of the most common strings expressing date in + this format may be something like @c "Sat, 18 Dec 1999 00:48:30 +0100". + + Returns @NULL if the conversion failed, otherwise return the pointer to + the character immediately following the part of the string which could be + parsed. If the entire string contains only the date in RFC 822 format, + the returned pointer will be pointing to a @c NUL character. + + This function is intentionally strict, it will return an error for any string + which is not RFC 822 compliant. If you need to parse date formatted in more + free ways, you should use ParseDateTime() or + ParseDate() instead. + */ + const char * ParseRfc822Date(const wxString& date, + wxString::const_iterator * end = @NULL); + const char * ParseRfc822Date(const char* date); + const wchar_t * ParseRfc822Date(const wchar_t* date); + //@} + + //@{ + /** + This functions is like ParseDateTime(), but + only allows the time to be specified in the input string. + + Returns @NULL if the conversion failed, otherwise return the pointer to + the character which stopped the scan. + */ + const char * ParseTime(const wxString& time, + wxString::const_iterator * end = @NULL); + const char * ParseTime(const char * time); + const wchar_t * ParseTime(const wchar_t * time); + //@} + + /** + These functions convert wxDateTime objects to and from text. The + conversions to text are mostly trivial: you can either do it using the default + date and time representations for the current locale ( + FormatDate() and + wxDateTime::FormatTime), using the international standard + representation defined by ISO 8601 ( + FormatISODate(), + FormatISOTime() and + wxDateTime::FormatISOCombined) or by specifying any + format at all and using Format() directly. + + The conversions from text are more interesting, as there are much more + possibilities to care about. The simplest cases can be taken care of with + ParseFormat() which can parse any date in the + given (rigid) format. wxDateTime::ParseRfc822Date is + another function for parsing dates in predefined format -- the one of RFC 822 + which (still...) defines the format of email messages on the Internet. This + format can not be described with @c strptime(3)-like format strings used by + Format(), hence the need for a separate function. + + But the most interesting functions are + ParseTime(), + ParseDate() and + ParseDateTime(). They try to parse the date + ans time (or only one of them) in 'free' format, i.e. allow them to be + specified in any of possible ways. These functions will usually be used to + parse the (interactive) user input which is not bound to be in any predefined + format. As an example, ParseDateTime() can + parse the strings such as @c "tomorrow", @c "March first" and even + @c "next Sunday". + + Finally notice that each of the parsing functions is available in several + overloads: if the input string is a narrow (@c char *) string, then a + narrow pointer is returned. If the input string is a wide string, a wide char + pointer is returned. Finally, if the input parameter is a wxString, a narrow + char pointer is also returned for backwards compatibility but there is also an + additional argument of wxString::const_iterator type in which, if it is not + @NULL, an iterator pointing to the end of the scanned string part is returned. + + ParseFormat() + + ParseDateTime() + + ParseDate() + + ParseTime() + + ParseISODate() + + ParseISOTime() + + ParseISOCombined() + + wxDateTime::ParseRfc822Date + + Format() + + FormatDate() + + FormatTime() + + FormatISOCombined() + + FormatISODate() + + FormatISOTime() + */ + + + /** + Reset time to midnight (00:00:00) without changing the date. + */ + wxDateTime ResetTime(); + + /** + Sets the date and time from the parameters. + */ +#define wxDateTime Set(wxDateTime_t day, Month month = Inv_Month, + int year = Inv_Year, + wxDateTime_t hour = 0, + wxDateTime_t minute = 0, + wxDateTime_t second = 0, + wxDateTime_t millisec = 0) /* implementation is private */ + + /** + Sets the country to use by default. This setting influences the DST + calculations, date formatting and other things. + + The possible values for @e country parameter are enumerated in + @ref overview_wxdatetime "wxDateTime constants section". + + @sa GetCountry() + */ + static void SetCountry(Country country); + + /** + Sets the day without changing other date components. + */ + wxDateTime SetDay(wxDateTime_t day); + + /** + Sets the date from the date and time in + DOS + format. + */ + wxDateTime Set(unsigned long ddt); + + /** + Sets the hour without changing other date components. + */ + wxDateTime SetHour(wxDateTime_t hour); + + /** + Sets the millisecond without changing other date components. + */ + wxDateTime SetMillisecond(wxDateTime_t millisecond); + + /** + Sets the minute without changing other date components. + */ + wxDateTime SetMinute(wxDateTime_t minute); + + /** + Sets the month without changing other date components. + */ + wxDateTime SetMonth(Month month); + + /** + Sets the second without changing other date components. + */ + wxDateTime SetSecond(wxDateTime_t second); + + /** + Sets the date and time of to the current values. Same as assigning the result + of Now() to this object. + */ + wxDateTime SetToCurrent(); + + /** + Sets the date to the last day in the specified month (the current one by + default). + + Returns the reference to the modified object itself. + */ + wxDateTime SetToLastMonthDay(Month month = Inv_Month, + int year = Inv_Year); + + /** + The effect of calling this function is the same as of calling + @c SetToWeekDay(-1, weekday, month, year). The date will be set to the last + @e weekday in the given month and year (the current ones by default). + + Always returns @true. + */ + bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month, + int year = Inv_Year); + + /** + Sets the date so that it will be the first @e weekday following the current + date. + + Returns the reference to the modified object itself. + */ + wxDateTime SetToNextWeekDay(WeekDay weekday); + + /** + Sets the date so that it will be the last @e weekday before the current + date. + + Returns the reference to the modified object itself. + */ + wxDateTime SetToPrevWeekDay(WeekDay weekday); + + /** + Sets the date to the @e n-th @e weekday in the given month of the given + year (the current month and year are used by default). The parameter @e n + may be either positive (counting from the beginning of the month) or negative + (counting from the end of it). + + For example, @c SetToWeekDay(2, wxDateTime::Wed) will set the date to the + second Wednesday in the current month and + @c 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. + */ + bool SetToWeekDay(WeekDay weekday, int n = 1, + Month month = Inv_Month, + int year = Inv_Year); + + /** + Adjusts the date so that it will still lie in the same week as before, but its + week day will be the given one. + + Returns the reference to the modified object itself. + */ + wxDateTime SetToWeekDayInSameWeek(WeekDay weekday, + WeekFlags flags = Monday_First); + + /** + Set the date to the given @e weekday in the week number @e numWeek of the + given @e year . The number should be in range 1...53. + + Note that the returned date may be in a different year than the one passed to + this function because both the week 1 and week 52 or 53 (for leap years) + contain days from different years. See + GetWeekOfYear() for the explanation of how the + year weeks are counted. + */ + static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek, + WeekDay weekday = Mon); + + /** + Sets the date to the day number @e yday in the same year (i.e., unlike the + other functions, this one does not use the current year). The day number + should be in the range 1...366 for the leap years and 1...365 for + the other ones. + + Returns the reference to the modified object itself. + */ + wxDateTime SetToYearDay(wxDateTime_t yday); + + /** + Sets the year without changing other date components. + */ + wxDateTime SetYear(int year); + + /** + For convenience, all static functions are collected here. These functions + either set or return the static variables of wxDateSpan (the country), return + the current moment, year, month or number of days in it, or do some general + calendar-related actions. + + Please note that although several function accept an extra @e Calendar + parameter, it is currently ignored as only the Gregorian calendar is + supported. Future versions will support other calendars. + SetCountry() + + GetCountry() + + IsWestEuropeanCountry() + + GetCurrentYear() + + ConvertYearToBC() + + GetCurrentMonth() + + IsLeapYear() + + @ref getcenturystatic() GetCentury + + GetNumberOfDays() + + GetNumberOfDays() + + GetMonthName() + + GetWeekDayName() + + GetAmPmStrings() + + IsDSTApplicable() + + GetBeginDST() + + GetEndDST() + + Now() + + UNow() + + Today() + */ + + + /** + Subtracts another date from this one and returns the difference between them + as wxTimeSpan. + */ + wxTimeSpan Subtract(const wxDateTime& dt); + + /** + Please see the @ref overview_tdatetimezones "time zone overview" for more + information about time zones. Normally, these functions should be rarely used. + + FromTimezone() + + ToTimezone() + + MakeTimezone() + + MakeFromTimezone() + + ToUTC() + + MakeUTC() + + GetBeginDST() + + GetEndDST() + + IsDST() + */ + + + /** + Transform the date to the given time zone. If @e noDST is @true, no + DST adjustments will be made. + + Returns the date in the new time zone. + */ + wxDateTime ToTimezone(const TimeZone& tz, bool noDST = @false); + + /** + This is the same as calling ToTimezone() with + the argument @c GMT0. + */ +#define wxDateTime ToUTC(bool noDST = @false) /* implementation is private */ + + /** + 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). + + @sa Now() + */ + static wxDateTime Today(); + + /** + Returns the object corresponding to the current time including the + milliseconds if a function to get time with such precision is available on the + current platform (supported under most Unices and Win32). + + @sa Now() + */ +#define static wxDateTime UNow() /* implementation is private */ + + /** + Same as @ref settm() Set. + */ + wxDateTime operator(const struct tm& tm); +}; + + +/** + @class wxDateTimeWorkDays + @wxheader{datetime.h} + + + @library{wxbase} + @category{FIXME} +*/ +class wxDateTimeWorkDays +{ +public: + +}; + + +/** + @class wxDateSpan + @wxheader{datetime.h} + + This class is a "logical time span" and is useful for implementing program + logic for such things as "add one month to the date" which, in general, + doesn't mean to add 60*60*24*31 seconds to it, but to take the same date + the next month (to understand that this is indeed different consider adding + one month to Feb, 15 -- we want to get Mar, 15, of course). + + When adding a month to the date, all lesser components (days, hours, ...) + won't be changed unless the resulting date would be invalid: for example, + Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31. + + Because of this feature, adding and subtracting back again the same + wxDateSpan will @b not, in general give back the original date: Feb 28 - 1 + month will be Jan 28, not Jan 31! + + wxDateSpan objects can be either positive or negative. They may be + multiplied by scalars which multiply all deltas by the scalar: i.e. + 2*(1 month and 1 day) is 2 months and 2 days. They can + be added together 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 @b every + source date. Thus wxDateSpan::Months(1) is not equal to wxDateSpan::Days(30), + because they don't give the same date when added to 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). + + @library{wxbase} + @category{data} + + @seealso + @ref overview_wxdatetimeoverview "Date classes overview", wxDateTime +*/ +class wxDateSpan +{ +public: + /** + Constructs the date span object for the given number of years, months, weeks + and days. Note that the weeks and days add together if both are given. + */ + wxDateSpan(int years = 0, int months = 0, int weeks = 0, + int days = 0); + + //@{ + /** + Returns the sum of two date spans. The first version returns a new object, the + second and third ones modify this object in place. + */ + wxDateSpan Add(const wxDateSpan& other); + wxDateSpan Add(const wxDateSpan& other); + wxDateSpan operator+=(const wxDateSpan& other); + //@} + + /** + Returns a date span object corresponding to one day. + + @sa Days() + */ +#define static wxDateSpan Day() /* implementation is private */ + + /** + Returns a date span object corresponding to the given number of days. + + @sa Day() + */ + static wxDateSpan Days(int days); + + /** + Returns the number of days (only, that it not counting the weeks component!) + in this date span. + + @sa GetTotalDays() + */ + int GetDays(); + + /** + Returns the number of the months (not counting the years) in this date span. + */ + int GetMonths(); + + /** + Returns the combined number of days in this date span, counting both weeks and + days. It still doesn't take neither months nor years into the account. + + @sa GetWeeks(), GetDays() + */ + int GetTotalDays(); + + /** + Returns the number of weeks in this date span. + + @sa GetTotalDays() + */ + int GetWeeks(); + + /** + Returns the number of years in this date span. + */ + int GetYears(); + + /** + Returns a date span object corresponding to one month. + + @sa Months() + */ + static wxDateSpan Month(); + + /** + Returns a date span object corresponding to the given number of months. + + @sa Month() + */ + static wxDateSpan Months(int mon); + + //@{ + /** + Returns the product of the date span by the specified @e 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. + */ + wxDateSpan Multiply(int factor); + wxDateSpan Multiply(int factor); + wxDateSpan operator*=(int factor); + //@} + + //@{ + /** + Changes the sign of this date span. + + @sa Negate() + */ + wxDateSpan Neg(); + wxDateSpan operator-(); + //@} + + /** + Returns the date span with the opposite sign. + + @sa Neg() + */ + wxDateSpan Negate(); + + /** + Sets the number of days (without modifying any other components) in this date + span. + */ + wxDateSpan SetDays(int n); + + /** + Sets the number of months (without modifying any other components) in this + date span. + */ + wxDateSpan SetMonths(int n); + + /** + Sets the number of weeks (without modifying any other components) in this date + span. + */ + wxDateSpan SetWeeks(int n); + + /** + Sets the number of years (without modifying any other components) in this date + span. + */ + wxDateSpan SetYears(int n); + + //@{ + /** + Returns the difference of two date spans. The first version returns a new + object, the second and third ones modify this object in place. + */ + wxDateSpan Subtract(const wxDateSpan& other); + wxDateSpan Subtract(const wxDateSpan& other); + wxDateSpan operator+=(const wxDateSpan& other); + //@} + + /** + Returns a date span object corresponding to one week. + + @sa Weeks() + */ + static wxDateSpan Week(); + + /** + Returns a date span object corresponding to the given number of weeks. + + @sa Week() + */ + static wxDateSpan Weeks(int weeks); + + /** + Returns a date span object corresponding to one year. + + @sa Years() + */ + static wxDateSpan Year(); + + /** + Returns a date span object corresponding to the given number of years. + + @sa Year() + */ + static wxDateSpan Years(int years); + + /** + Returns @true if this date span is different from the other one. + */ + bool operator!=(wxDateSpan& other); + + /** + Returns @true if this date span is equal to the other one. Two date spans + are considered equal if and only if they have the same number of years and + months and the same total number of days (counting both days and weeks). + */ + bool operator==(wxDateSpan& other); +}; + + +/** + @class wxTimeSpan + @wxheader{datetime.h} + + wxTimeSpan class represents a time interval. + + @library{wxbase} + @category{data} + + @seealso + @ref overview_wxdatetimeoverview "Date classes overview", wxDateTime +*/ +class wxTimeSpan +{ +public: + //@{ + /** + Constructs timespan from separate values for each component, with the date + set to 0. Hours are not restricted to 0..24 range, neither are + minutes, seconds or milliseconds. + */ + wxTimeSpan(); + wxTimeSpan(long hours, long min, long sec, long msec); + //@} + + /** + Returns the absolute value of the timespan: does not modify the + object. + */ +#define wxTimeSpan Abs() /* implementation is private */ + + /** + GetSeconds() + + GetMinutes() + + GetHours() + + GetDays() + + GetWeeks() + + GetValue() + */ + + + //@{ + /** + Returns the sum of two timespans. + */ + wxTimeSpan Add(const wxTimeSpan& diff); + wxTimeSpan Add(const wxTimeSpan& diff); + wxTimeSpan operator+=(const wxTimeSpan& diff); + //@} + + /** + @ref ctor() wxTimeSpan + */ + + + /** + Returns the timespan for one day. + */ +#define static wxTimespan Day() /* implementation is private */ + + /** + Returns the timespan for the given number of days. + */ + static wxTimespan Days(long days); + + /** + Returns the string containing the formatted representation of the time span. + The following format specifiers are allowed after %: + + H + + + number of @b Hours + + M + + + number of @b Minutes + + S + + + number of @b Seconds + + l + + + number of mi@b lliseconds + + D + + + number of @b Days + + E + + + number of w@b Eeks + + % + + + the percent character + + Note that, for example, the number of hours in the description above is not + well defined: it can be either the total number of hours (for example, for a + time span of 50 hours this would be 50) or just the hour part of the time + span, which would be 2 in this case as 50 hours is equal to 2 days and + 2 hours. + + wxTimeSpan resolves this ambiguity in the following way: if there had been, + indeed, the @c %D format specified preceding the @c %H, then it is + interpreted as 2. Otherwise, it is 50. + + The same applies to all other format specifiers: if they follow a specifier of + larger unit, only the rest part is taken, otherwise the full value is used. + */ + wxString Format(const wxChar * format = wxDefaultTimeSpanFormat); + + /** + Format() + */ + + + /** + Returns the difference in number of days. + */ + int GetDays(); + + /** + Returns the difference in number of hours. + */ + int GetHours(); + + /** + Returns the difference in number of milliseconds. + */ + wxLongLong GetMilliseconds(); + + /** + Returns the difference in number of minutes. + */ + int GetMinutes(); + + /** + Returns the difference in number of seconds. + */ + wxLongLong GetSeconds(); + + /** + Returns the internal representation of timespan. + */ + wxLongLong GetValue(); + + /** + Returns the difference in number of weeks. + */ + int GetWeeks(); + + /** + Returns the timespan for one hour. + */ + static wxTimespan Hour(); + + /** + Returns the timespan for the given number of hours. + */ + static wxTimespan Hours(long hours); + + /** + Returns @true if two timespans are equal. + */ + bool IsEqualTo(const wxTimeSpan& ts); + + /** + Compares two timespans: works with the absolute values, i.e. -2 + hours is longer than 1 hour. Also, it will return @false if + the timespans are equal in absolute value. + */ + bool IsLongerThan(const wxTimeSpan& ts); + + /** + Returns @true if the timespan is negative. + */ + bool IsNegative(); + + /** + Returns @true if the timespan is empty. + */ + bool IsNull(); + + /** + Returns @true if the timespan is positive. + */ + bool IsPositive(); + + /** + Compares two timespans: works with the absolute values, i.e. 1 + hour is shorter than -2 hours. Also, it will return @false if + the timespans are equal in absolute value. + */ + bool IsShorterThan(const wxTimeSpan& ts); + + /** + Returns the timespan for one millisecond. + */ + static wxTimespan Millisecond(); + + /** + Returns the timespan for the given number of milliseconds. + */ + static wxTimespan Milliseconds(long ms); + + /** + Returns the timespan for one minute. + */ + static wxTimespan Minute(); + + /** + Returns the timespan for the given number of minutes. + */ + static wxTimespan Minutes(long min); + + //@{ + /** + Multiplies timespan by a scalar. + */ + wxTimeSpan Multiply(int n); + wxTimeSpan Multiply(int n); + wxTimeSpan operator*=(int n); + //@} + + //@{ + /** + Negate the value of the timespan. + */ + wxTimeSpan Neg(); + wxTimeSpan operator-(); + //@} + + /** + Returns timespan with inverted sign. + */ + wxTimeSpan Negate(); + + /** + Add() + + Subtract() + + Multiply() + + Negate() + + Neg() + + Abs() + */ + + + /** + Returns the timespan for one second. + */ + static wxTimespan Second(); + + /** + Returns the timespan for the given number of seconds. + */ + static wxTimespan Seconds(long sec); + + /** + Milliseconds() + + Millisecond() + + Seconds() + + Second() + + Minutes() + + Minute() + + Hours() + + Hour() + + Days() + + Day() + + Weeks() + + Week() + */ + + + //@{ + /** + Returns the difference of two timespans. + */ + wxTimeSpan Subtract(const wxTimeSpan& diff); + wxTimeSpan Subtract(const wxTimeSpan& diff); + wxTimeSpan operator-=(const wxTimeSpan& diff); + //@} + + /** + IsNull() + + IsPositive() + + IsNegative() + + IsEqualTo() + + IsLongerThan() + + IsShorterThan() + */ + + + /** + Returns the timespan for one week. + */ + static wxTimespan Week(); + + /** + Returns the timespan for the given number of weeks. + */ + static wxTimespan Weeks(long weeks); +}; + + +/** + @class wxDateTimeHolidayAuthority + @wxheader{datetime.h} + + + @library{wxbase} + @category{FIXME} +*/ +class wxDateTimeHolidayAuthority +{ +public: + +}; diff --git a/interface/datstrm.h b/interface/datstrm.h new file mode 100644 index 0000000000..28e2a7e480 --- /dev/null +++ b/interface/datstrm.h @@ -0,0 +1,263 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: datstrm.h +// Purpose: documentation for wxDataOutputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDataOutputStream + @wxheader{datstrm.h} + + This class provides functions that write binary data types in a + portable way. Data can be written in either big-endian or little-endian + format, little-endian being the default on all architectures. + + If you want to write data to text files (or streams) use + wxTextOutputStream instead. + + The operator is overloaded and you can use this class like a standard + C++ iostream. See wxDataInputStream for its + usage and caveats. + + See also wxDataInputStream. + + @library{wxbase} + @category{streams} +*/ +class wxDataOutputStream +{ +public: + //@{ + /** + ) + + 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. + + @param stream + The output stream. + + @param conv + Charset conversion object object used to encoding Unicode + strings before writing them to the stream + in Unicode mode (see WriteString() + documentation for detailed description). Note that you must not destroy + conv before you destroy this wxDataOutputStream instance! It is + recommended to use default value (UTF-8). + */ + wxDataOutputStream(wxOutputStream& stream); + wxDataOutputStream(wxOutputStream& stream); + //@} + + /** + Destroys the wxDataOutputStream object. + */ + ~wxDataOutputStream(); + + /** + If @e be_order is @true, all data will be written in big-endian + order, e.g. for reading on a Sparc or from Java-Streams (which + always use big-endian order), otherwise data will be written in + little-endian order. + */ + void BigEndianOrdered(bool be_order); + + //@{ + /** + Writes an array of 16 bit unsigned integer to the stream. The amount of + 16 bit unsigned integer to write is specified with the @e size variable. + */ + void Write16(wxUint16 i16); + void Write16(const wxUint16 * buffer, size_t size); + //@} + + //@{ + /** + Writes an array of 32 bit unsigned integer to the stream. The amount of + 32 bit unsigned integer to write is specified with the @e size variable. + */ + void Write32(wxUint32 i32); + void Write32(const wxUint32 * buffer, size_t size); + //@} + + //@{ + /** + Writes an array of 64 bit unsigned integer to the stream. The amount of + 64 bit unsigned integer to write is specified with the @e size variable. + */ + void Write64(wxUint64 i64); + void Write64(const wxUint64 * buffer, size_t size); + //@} + + //@{ + /** + Writes an array of bytes to the stream. The amount of bytes to write is + specified with the @e size variable. + */ + void Write8(wxUint8 i8); + void Write8(const wxUint8 * buffer, size_t size); + //@} + + //@{ + /** + Writes an array of double to the stream. The amount of double to write is + specified with the @e size variable. + */ + void WriteDouble(double f); + void WriteDouble(const double * buffer, size_t size); + //@} + + /** + Writes @e string to the stream. Actually, this method writes the size of + the string before writing @e string itself. + + In ANSI build of wxWidgets, the string is written to the stream in exactly + same way it is represented in memory. In Unicode build, however, the string + is first converted to multibyte representation with @e conv object passed + to stream's constructor (consequently, ANSI 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. + */ + void WriteString(const wxString& string); +}; + + +/** + @class wxDataInputStream + @wxheader{datstrm.h} + + This class provides functions that read binary data types in a + portable way. Data can be read in either big-endian or little-endian + format, little-endian being the default on all architectures. + + If you want to read data from text files (or streams) use + wxTextInputStream instead. + + The operator is overloaded and you can use this class like a standard C++ + iostream. + Note, however, that the arguments are the fixed size types wxUint32, wxInt32 etc + and on a typical 32-bit computer, none of these match to the "long" type + (wxInt32 + is defined as signed int on 32-bit architectures) so that you cannot use long. + To avoid + problems (here and elsewhere), make use of the wxInt32, wxUint32, etc types. + + For example: + + @code + wxFileInputStream input( "mytext.dat" ); + wxDataInputStream store( input ); + wxUint8 i1; + float f2; + wxString line; + + store i1; // read a 8 bit integer. + store i1 f2; // read a 8 bit integer followed by float. + store line; // read a text line + @endcode + + See also wxDataOutputStream. + + @library{wxbase} + @category{streams} +*/ +class wxDataInputStream +{ +public: + //@{ + /** + ) + + 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. + + @param stream + The input stream. + + @param conv + Charset conversion object object used to decode strings in Unicode + mode (see ReadString() + documentation for detailed description). Note that you must not destroy + conv before you destroy this wxDataInputStream instance! + */ + wxDataInputStream(wxInputStream& stream); + wxDataInputStream(wxInputStream& stream); + //@} + + /** + Destroys the wxDataInputStream object. + */ + ~wxDataInputStream(); + + /** + If @e be_order is @true, all data will be read in big-endian + order, such as written by programs on a big endian architecture + (e.g. Sparc) or written by Java-Streams (which always use + big-endian order). + */ + void BigEndianOrdered(bool be_order); + + //@{ + /** + Reads 16 bit unsigned integers from the stream in a specified buffer. the + amount of 16 bit unsigned integer to read is specified by the @e size variable. + */ + wxUint16 Read16(); + void Read16(wxUint16 * buffer, size_t size); + //@} + + //@{ + /** + 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 @e size variable. + */ + wxUint32 Read32(); + void Read32(wxUint32 * buffer, size_t size); + //@} + + //@{ + /** + 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 @e size variable. + */ + wxUint64 Read64(); + void Read64(wxUint64 * buffer, size_t size); + //@} + + //@{ + /** + Reads bytes from the stream in a specified buffer. The amount of + bytes to read is specified by the @e size variable. + */ + wxUint8 Read8(); + void Read8(wxUint8 * buffer, size_t size); + //@} + + //@{ + /** + Reads double data (IEEE encoded) from the stream in a specified buffer. the + amount of + double to read is specified by the @e size variable. + */ + double ReadDouble(); + void ReadDouble(double * buffer, size_t size); + //@} + + /** + Reads a string from a stream. Actually, this function first reads a long + integer specifying the length of the string (without the last null character) + and then reads the string. + + In Unicode build of wxWidgets, the fuction first reads multibyte (char*) + string from the stream and then converts it to Unicode using the @e conv + object passed to constructor and returns the result as wxString. You are + responsible for using the same convertor as when writing the stream. + + See also wxDataOutputStream::WriteString. + */ + wxString ReadString(); +}; diff --git a/interface/dc.h b/interface/dc.h new file mode 100644 index 0000000000..f5258f82a5 --- /dev/null +++ b/interface/dc.h @@ -0,0 +1,1088 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dc.h +// Purpose: documentation for wxDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDC + @wxheader{dc.h} + + A wxDC is a @e device context onto which graphics and text can be drawn. + It is intended to represent 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. + + Notice that wxDC is an abstract base class and can't be created directly, + please use wxPaintDC, wxClientDC, + wxWindowDC, wxScreenDC, + wxMemoryDC or wxPrinterDC. + + Please note that in addition to the versions of the methods documented here, + there are also versions which accept single @c wxPoint parameter instead of + two @c wxCoord ones or @c wxPoint and @c wxSize instead of four of + them. + + @library{wxcore} + @category{dc} + + @seealso + Overview +*/ +class wxDC : public wxObject +{ +public: + /** + Copy from a source DC to this DC, specifying the destination + coordinates, size of area to copy, source DC, source coordinates, + logical function, whether to use a bitmap mask, and mask source position. + + @param xdest + Destination device context x position. + + @param ydest + Destination device context y position. + + @param width + Width of source area to be copied. + + @param height + Height of source area to be copied. + + @param source + Source device context. + + @param xsrc + Source device context x position. + + @param ysrc + Source device context y position. + + @param logicalFunc + Logical function to use: see SetLogicalFunction(). + + @param useMask + If @true, Blit does a transparent blit using the mask that is associated with + the bitmap + selected into the source device context. The Windows implementation does the + following if MaskBlt cannot be used: + + Creates a temporary bitmap and copies the destination area into it. + Copies the source area into the temporary bitmap using the specified logical + function. + Sets the masked area in the temporary bitmap to BLACK by ANDing the + mask bitmap with the temp bitmap with the foreground colour set to WHITE + and the bg colour set to BLACK. + Sets the unmasked area in the destination area to BLACK by ANDing the + mask bitmap with the destination area with the foreground colour set to BLACK + and the background colour set to WHITE. + ORs the temporary bitmap with the destination area. + Deletes the temporary bitmap. + + This sequence of operations ensures that the source's transparent area need not + be black, + and logical functions are supported. + + Note: on Windows, blitting with masks can be speeded up considerably by + compiling + wxWidgets with the wxUSE_DC_CACHE option enabled. You can also influence + whether MaskBlt + or the explicit mask blitting code above is used, by using wxSystemOptions and + setting the no-maskblt option to 1. + @param xsrcMask + Source x position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and + ysrc + will be assumed for the mask source position. Currently only implemented on + Windows. + + @param ysrcMask + Source y position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and + ysrc + will be assumed for the mask source position. Currently only implemented on + Windows. + + @remarks There is partial support for Blit in wxPostScriptDC, under X. + + @sa StretchBlit(), wxMemoryDC, wxBitmap, wxMask + */ + bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, + wxCoord height, wxDC* source, + wxCoord xsrc, wxCoord ysrc, + int logicalFunc = wxCOPY, + bool useMask = @false, + wxCoord xsrcMask = -1, + wxCoord ysrcMask = -1); + + /** + Adds the specified point to the bounding box which can be retrieved with + MinX(), MaxX() and + MinY(), MaxY() functions. + + @sa ResetBoundingBox() + */ + void CalcBoundingBox(wxCoord x, wxCoord y); + + /** + Clears the device context using the current background brush. + */ + void Clear(); + + /** + Performs all necessary computations for given platform and context type + after each change of scale and origin parameters. Usually called automatically + internally after such changes. + */ + virtual void ComputeScaleAndOrigin(); + + /** + Displays a cross hair using the current pen. This is a vertical + and horizontal line the height and width of the window, centred + on the given point. + */ + void CrossHair(wxCoord x, wxCoord y); + + /** + Destroys the current clipping region so that none of the DC is clipped. + See also SetClippingRegion(). + */ + void DestroyClippingRegion(); + + /** + Convert device X coordinate to logical coordinate, using the current + mapping mode. + */ + virtual wxCoord DeviceToLogicalX(wxCoord x); + + /** + Convert device X coordinate to relative logical coordinate, using the current + mapping mode but ignoring the x axis orientation. + Use this function for converting a width, for example. + */ + virtual wxCoord DeviceToLogicalXRel(wxCoord x); + + /** + Converts device Y coordinate to logical coordinate, using the current + mapping mode. + */ + virtual wxCoord DeviceToLogicalY(wxCoord y); + + /** + Convert device Y coordinate to relative logical coordinate, using the current + mapping mode but ignoring the y axis orientation. + Use this function for converting a height, for example. + */ + virtual wxCoord DeviceToLogicalYRel(wxCoord y); + + /** + Draws an arc of a circle, centred on (@e xc, yc), with starting point (@e x1, + y1) + and ending at (@e 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. + */ + void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, + wxCoord xc, wxCoord yc); + + /** + Draw a bitmap on the device context at the specified point. If @e 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. + */ + void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, + bool transparent); + + //@{ + /** + Draws a check mark inside the given rectangle. + */ + void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + void DrawCheckMark(const wxRect & rect); + //@} + + //@{ + /** + Draws a circle with the given centre and radius. + + @sa DrawEllipse() + */ + void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); + void DrawCircle(const wxPoint& pt, wxCoord radius); + //@} + + //@{ + /** + Draws an ellipse contained in the rectangle specified either with the given top + left corner and the given size or directly. The current pen is used for the + outline and the current brush for filling the shape. + + @sa DrawCircle() + */ + void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + void DrawEllipse(const wxPoint& pt, const wxSize& size); + void DrawEllipse(const wxRect& rect); + //@} + + /** + Draws an arc of an ellipse. The current pen is used for drawing the arc and + the current brush is used for drawing the pie. + + @e x and @e y specify the x and y coordinates of the upper-left corner of the + rectangle that contains + the ellipse. + + @e width and @e height specify the width and height of the rectangle that + contains + the ellipse. + + @e start and @e 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 @e start is equal to @e end, a + complete ellipse will be drawn. + */ + void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, + wxCoord height, + double start, + double end); + + /** + Draw an icon on the display (does nothing if the device context is PostScript). + This can be the simplest way of drawing bitmaps on a window. + */ + void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); + + //@{ + /** + Draw optional bitmap and the text into the given rectangle and aligns it as + specified + by alignment parameter; it also will emphasize the character with the given + index if + it is != -1 and return the bounding rectangle if required. + */ + virtual void DrawLabel(const wxString& text, + const wxBitmap& image, + const wxRect& rect, + int alignment = wxALIGN_LEFT | wxALIGN_TOP, + int indexAccel = -1, + wxRect * rectBounding = @NULL); + void DrawLabel(const wxString& text, const wxRect& rect, + int alignment = wxALIGN_LEFT | wxALIGN_TOP, + int indexAccel = -1); + //@} + + /** + Draws a line from the first point to the second. The current pen is used + for drawing the line. Note that the point (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). + */ + void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); + + //@{ + /** + This method uses a list of wxPoints, adding the optional offset + coordinate. The programmer is responsible for deleting the list + of points. + */ + void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, + wxCoord yoffset = 0); + void DrawLines(const wxPointList * points, + wxCoord xoffset = 0, + wxCoord yoffset = 0); + //@} + + /** + Draws a point using the color of the current pen. Note that the other + properties of the pen are not used, such as width etc.. + */ + void DrawPoint(wxCoord x, wxCoord y); + + /** + Draws two or more filled polygons using an array of @e 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. + + @e n specifies the number of polygons to draw, the array @e count of size + @e n specifies the number of points in each of the polygons in the + @e points array. + + The last argument specifies the fill rule: @b wxODDEVEN_RULE (the default) + or @b wxWINDING_RULE. + + The current pen is used for drawing the outline, and the current brush for + filling the shape. Using a transparent brush suppresses filling. + + The polygons maybe disjoint or overlapping. Each polygon specified in a call to + @b DrawPolyPolygon must be closed. Unlike polygons created by the + DrawPolygon() member function, the polygons created by + @b DrawPolyPolygon are not closed automatically. + */ + void DrawPolyPolygon(int n, int count[], wxPoint points[], + wxCoord xoffset = 0, + wxCoord yoffset = 0, + int fill_style = wxODDEVEN_RULE); + + //@{ + /** + This method draws a filled polygon using a list of wxPoints, + adding the optional offset coordinate. + + The last argument specifies the fill rule: @b wxODDEVEN_RULE (the + default) or @b wxWINDING_RULE. + + The current pen is used for drawing the outline, and the current brush + for filling the shape. Using a transparent brush suppresses filling. + The programmer is responsible for deleting the list of points. + + Note that wxWidgets automatically closes the first and last points. + */ + void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, + wxCoord yoffset = 0, + int fill_style = wxODDEVEN_RULE); + void DrawPolygon(const wxPointList * points, + wxCoord xoffset = 0, + wxCoord yoffset = 0, + int fill_style = wxODDEVEN_RULE); + //@} + + /** + Draws a rectangle with the given top left corner, and with the given + size. The current pen is used for the outline and the current brush + for filling the shape. + */ + void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + + /** + Draws the text rotated by @e angle degrees. + + @b NB: Under Win9x only TrueType fonts can be drawn by this function. In + particular, a font different from @c wxNORMAL_FONT should be used as the + latter is not a TrueType font. @c wxSWISS_FONT is an example of a font + which is. + + @sa DrawText() + */ + void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, + double angle); + + /** + Draws a rectangle with the given top left corner, and with the given + size. The corners are quarter-circles using the given radius. The + current pen is used for the outline and the current brush for filling + the shape. + + If @e radius is positive, the value is assumed to be the + radius of the rounded corner. If @e radius is negative, + the absolute value is assumed to be the @e proportion of the smallest + dimension of the rectangle. This means that the corner can be + a sensible size relative to the size of the rectangle, and also avoids + the strange effects X produces when the corners are too big for + the rectangle. + */ + void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, + wxCoord height, + double radius); + + //@{ + /** + Draws a three-point spline using the current pen. + */ + void DrawSpline(int n, wxPoint points[]); + void DrawSpline(const wxPointList * points); + void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, + wxCoord y2, + wxCoord x3, + wxCoord y3); + //@} + + /** + Draws a text string at the specified point, using the current text font, + and the current text foreground and background colours. + + The coordinates refer to the top-left corner of the rectangle bounding + the string. See GetTextExtent() for how + to get the dimensions of a text string, which can be used to position the + text more precisely. + + @b NB: under wxGTK the current + @ref getlogicalfunction() "logical function" is used by this function + but it is ignored by wxMSW. Thus, you should avoid using logical functions + with this function in portable programs. + */ + void DrawText(const wxString& text, wxCoord x, wxCoord y); + + /** + Ends a document (only relevant when outputting to a printer). + */ + void EndDoc(); + + /** + Ends a document page (only relevant when outputting to a printer). + */ + void EndPage(); + + /** + Flood fills the device context starting from the given point, using + the @e current brush colour, and using a style: + + wxFLOOD_SURFACE: the flooding occurs until a colour other than the given + colour is encountered. + wxFLOOD_BORDER: the area to be flooded is bounded by the given colour. + + Returns @false if the operation failed. + + @e Note: The present implementation for non-Windows platforms may fail to find + colour borders if the pixels do not match the colour exactly. However the + function will still return @true. + */ + bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, + int style=wxFLOOD_SURFACE); + + /** + Gets the brush used for painting the background (see wxDC::SetBackground). + */ + const wxBrush GetBackground(); + + /** + Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. + + @sa SetBackgroundMode() + */ + int GetBackgroundMode(); + + /** + Gets the current brush (see wxDC::SetBrush). + */ + const wxBrush GetBrush(); + + /** + Gets the character height of the currently set font. + */ + wxCoord GetCharHeight(); + + /** + Gets the average character width of the currently set font. + */ + wxCoord GetCharWidth(); + + /** + Gets the rectangle surrounding the current clipping region. + */ + void GetClippingBox(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + + /** + Returns the depth (number of bits/pixel) of this DC. + + @sa wxDisplayDepth + */ + int GetDepth(); + + /** + Gets the current font. Notice that even although each device context object has + some default font after creation, this method would return a @c wxNullFont + initially and only after calling SetFont() a valid + font is returned. + */ + const wxFont GetFont(); + + /** + Gets the current layout direction of the device context. On platforms where RTL + layout + is supported, the return value will either be @c wxLayout_LeftToRight or + @c wxLayout_RightToLeft. If RTL layout is not supported, the return value will + be @c wxLayout_Default. + + @sa SetLayoutDirection() + */ + wxLayoutDirection GetLayoutDirection(); + + /** + Gets the current logical function (see wxDC::SetLogicalFunction). + */ + int GetLogicalFunction(); + + /** + Gets the @e mapping mode for the device context (see wxDC::SetMapMode). + */ + int GetMapMode(); + + //@{ + /** + Gets the dimensions of the string using the currently selected font. + @e string is the text string to measure, @e heightLine, if non @NULL, + is where to store the height of a single line. + + The text extent is returned in @e w and @e h pointers (first form) or as + a wxSize object (second form). + + If the optional parameter @e font is specified and valid, then it is used + for the text extent calculation. Otherwise the currently selected font is. + + Note that this function works both with single-line and multi-line strings. + + @sa wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() + */ + void GetMultiLineTextExtent(const wxString& string, wxCoord * w, + wxCoord * h, + wxCoord * heightLine = @NULL, + wxFont * font = @NULL); + wxSize GetMultiLineTextExtent(const wxString& string); + //@} + + /** + Returns the resolution of the device in pixels per inch. + */ +#define wxSize GetPPI() /* implementation is private */ + + /** + Fills the @e widths array with the widths from the beginning of + @e text to the corresponding character of @e 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. + + @sa GetMultiLineTextExtent(), GetTextExtent() + */ + bool GetPartialTextExtents(const wxString& text, + wxArrayInt& widths); + + /** + Gets the current pen (see wxDC::SetPen). + */ + const wxPen GetPen(); + + /** + Gets in @e colour the colour at the specified location. + Not available for wxPostScriptDC or wxMetafileDC. + + Note that setting a pixel can be done using DrawPoint(). + */ + bool GetPixel(wxCoord x, wxCoord y, wxColour * colour); + + //@{ + /** + This gets the horizontal and vertical resolution in device units. It can be + used to scale graphics to fit the page. + For example, if @e maxX and @e maxY + represent the maximum horizontal and vertical 'pixel' values used in your + application, the following code will scale the graphic to fit on the + printer page: + + + + @b GetSize() + + + Returns a Wx::Size + + @b GetSizeWH() + + + Returns a 2-element list + @c ( width, height ) + */ + void GetSize(wxCoord * width, wxCoord * height); + wxSize GetSize(); + //@} + + //@{ + /** + Returns the horizontal and vertical resolution in millimetres. + */ + void GetSizeMM(wxCoord * width, wxCoord * height); + wxSize GetSizeMM(); + //@} + + /** + Gets the current text background colour (see wxDC::SetTextBackground). + */ + const wxColour GetTextBackground(); + + //@{ + /** + Gets the dimensions of the string using the currently selected font. + @e string is the text string to measure, @e descent is the + dimension from the baseline of the font to the bottom of the + descender, and @e externalLeading is any extra vertical space added + to the font by the font designer (usually is zero). + + The text extent is returned in @e w and @e h pointers (first form) or as + a wxSize object (second form). + + If the optional parameter @e font is specified and valid, then it is used + for the text extent calculation. Otherwise the currently selected font is. + + Note that this function only works with single-line strings. + + @sa wxFont, SetFont(), GetPartialTextExtents(), + GetMultiLineTextExtent() + */ + void GetTextExtent(const wxString& string, wxCoord * w, + wxCoord * h, + wxCoord * descent = @NULL, + wxCoord * externalLeading = @NULL, + const wxFont * font = @NULL); + wxSize GetTextExtent(const wxString& string); + //@} + + /** + Gets the current text foreground colour (see wxDC::SetTextForeground). + */ + const wxColour GetTextForeground(); + + /** + Gets the current user scale factor (set by wxDC::SetUserScale). + */ + void GetUserScale(double x, double y); + + //@{ + /** + Fill the area specified by rect with a radial gradient, starting from + @e initialColour at the centre of the circle and fading to @e destColour + on the circle outside. + + @e circleCenter are the relative coordinates of centre of the circle in + the specified @e rect. If not specified, the cercle is placed at the + centre of rect. + + @b Note: Currently this function is very slow, don't use it for + real-time drawing. + */ + void GradientFillConcentric(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour); + void GradientFillConcentric(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour, + const wxPoint& circleCenter); + //@} + + /** + Fill the area specified by @e rect with a linear gradient, starting from + @e initialColour and eventually fading to @e destColour. The + @e nDirection specifies the direction of the colour change, default is to + use @e initialColour on the left part of the rectangle and + @e destColour on the right one. + */ + void GradientFillLinear(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour, + wxDirection nDirection = wxEAST); + + /** + Returns @true if the DC is ok to use. + */ +#define bool Ok() /* implementation is private */ + + /** + Converts logical X coordinate to device coordinate, using the current + mapping mode. + */ + virtual wxCoord LogicalToDeviceX(wxCoord x); + + /** + Converts logical X coordinate to relative device coordinate, using the current + mapping mode but ignoring the x axis orientation. + Use this for converting a width, for example. + */ + virtual wxCoord LogicalToDeviceXRel(wxCoord x); + + /** + Converts logical Y coordinate to device coordinate, using the current + mapping mode. + */ + virtual wxCoord LogicalToDeviceY(wxCoord y); + + /** + Converts logical Y coordinate to relative device coordinate, using the current + mapping mode but ignoring the y axis orientation. + Use this for converting a height, for example. + */ + virtual wxCoord LogicalToDeviceYRel(wxCoord y); + + /** + Gets the maximum horizontal extent used in drawing commands so far. + */ +#define wxCoord MaxX() /* implementation is private */ + + /** + Gets the maximum vertical extent used in drawing commands so far. + */ +#define wxCoord MaxY() /* implementation is private */ + + /** + Gets the minimum horizontal extent used in drawing commands so far. + */ +#define wxCoord MinX() /* implementation is private */ + + /** + Gets the minimum vertical extent used in drawing commands so far. + */ +#define wxCoord MinY() /* implementation is private */ + + /** + Resets the bounding box: after a call to this function, the bounding box + doesn't contain anything. + + @sa CalcBoundingBox() + */ + void ResetBoundingBox(); + + /** + Sets the x and y axis orientation (i.e., the direction from lowest to + highest values on the axis). The default orientation is + x axis from left to right and y axis from top down. + + @param xLeftRight + True to set the x axis orientation to the natural + left to right orientation, @false to invert it. + + @param yBottomUp + True to set the y axis orientation to the natural + bottom up orientation, @false to invert it. + */ + void SetAxisOrientation(bool xLeftRight, bool yBottomUp); + + /** + Sets the current background brush for the DC. + */ + void SetBackground(const wxBrush& brush); + + /** + @e mode may be one of wxSOLID and wxTRANSPARENT. This setting determines + whether text will be drawn with a background colour or not. + */ + void SetBackgroundMode(int mode); + + /** + Sets the current brush for the DC. + + If the argument is wxNullBrush, the current brush is selected out of the device + context (leaving wxDC without any valid brush), allowing the current brush to + be destroyed safely. + + See also wxBrush. + + See also wxMemoryDC for the interpretation of colours + when drawing into a monochrome bitmap. + */ + void SetBrush(const wxBrush& brush); + + //@{ + /** + Sets the clipping region for this device context to the intersection of the + given region described by the parameters of this method and the previously set + clipping region. You should call + DestroyClippingRegion() if you want to set + the clipping region exactly to the region specified. + + The clipping region is an area to which drawing is restricted. Possible uses + for the clipping region are for clipping text or for speeding up window redraws + when only a known area of the screen is damaged. + + @sa DestroyClippingRegion(), wxRegion + */ + void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + void SetClippingRegion(const wxPoint& pt, const wxSize& sz); + void SetClippingRegion(const wxRect& rect); + void SetClippingRegion(const wxRegion& region); + //@} + + /** + Sets the device origin (i.e., the origin in pixels after scaling has been + applied). + + This function may be useful in Windows printing + operations for placing a graphic on a page. + */ + void SetDeviceOrigin(wxCoord x, wxCoord y); + + /** + Sets the current font for the DC. It must be a valid font, in particular you + should not pass @c wxNullFont to this method. + + See also wxFont. + */ + void SetFont(const wxFont& font); + + /** + Sets the current layout direction for the device context. @e dir may be either + @c wxLayout_Default, @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. + + @sa GetLayoutDirection() + */ + void SetLayoutDirection(wxLayoutDirection dir); + + /** + Sets the current logical function for the device context. This determines how + a source pixel (from a pen or brush colour, or source device context if + using 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: + The default is wxCOPY, which simply draws with the current colour. + The others combine the current colour and the background using a + logical operation. wxINVERT is commonly used for drawing rubber bands or + moving outlines, since drawing twice reverts to the original colour. + */ + void SetLogicalFunction(int function); + + /** + The @e 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 @e 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 device pixel. + */ + void SetMapMode(int int); + + /** + 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. + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the current pen for the DC. + + If the argument is wxNullPen, the current pen is selected out of the device + context (leaving wxDC without any valid pen), allowing the current brush to + be destroyed safely. + + See also wxMemoryDC for the interpretation of colours + when drawing into a monochrome bitmap. + */ + void SetPen(const wxPen& pen); + + /** + Sets the current text background colour for the DC. + */ + void SetTextBackground(const wxColour& colour); + + /** + Sets the current text foreground colour for the DC. + + See also wxMemoryDC for the interpretation of colours + when drawing into a monochrome bitmap. + */ + void SetTextForeground(const wxColour& colour); + + /** + Sets the user scaling factor, useful for applications which require + 'zooming'. + */ + void SetUserScale(double xScale, double yScale); + + /** + Starts a document (only relevant when outputting to a printer). + Message is a message to show while printing. + */ + bool StartDoc(const wxString& message); + + /** + Starts a document page (only relevant when outputting to a printer). + */ + bool StartPage(); + + /** + Copy from a source DC to this DC, specifying the destination + coordinates, destination size, source DC, source coordinates, + size of source area to copy, logical function, whether to use a bitmap mask, + and mask source position. + + @param xdest + Destination device context x position. + + @param ydest + Destination device context y position. + + @param dstWidth + Width of destination area. + + @param dstHeight + Height of destination area. + + @param source + Source device context. + + @param xsrc + Source device context x position. + + @param ysrc + Source device context y position. + + @param srcWidth + Width of source area to be copied. + + @param srcHeight + Height of source area to be copied. + + @param logicalFunc + Logical function to use: see SetLogicalFunction(). + + @param useMask + If @true, Blit does a transparent blit using the mask that is associated with + the bitmap + selected into the source device context. The Windows implementation does the + following if MaskBlt cannot be used: + + Creates a temporary bitmap and copies the destination area into it. + Copies the source area into the temporary bitmap using the specified logical + function. + Sets the masked area in the temporary bitmap to BLACK by ANDing the + mask bitmap with the temp bitmap with the foreground colour set to WHITE + and the background colour set to BLACK. + Sets the unmasked area in the destination area to BLACK by ANDing the + mask bitmap with the destination area with the foreground colour set to BLACK + and the background colour set to WHITE. + ORs the temporary bitmap with the destination area. + Deletes the temporary bitmap. + + This sequence of operations ensures that the source's transparent area need not + be black, + and logical functions are supported. + + Note: on Windows, blitting with masks can be speeded up considerably by + compiling + wxWidgets with the wxUSE_DC_CACHE option enabled. You can also influence + whether MaskBlt + or the explicit mask blitting code above is used, by using wxSystemOptions and + setting the no-maskblt option to 1. + @param xsrcMask + Source x position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and + ysrc + will be assumed for the mask source position. Currently only implemented on + Windows. + + @param ysrcMask + Source y position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and + ysrc + will be assumed for the mask source position. Currently only implemented on + Windows. + + @remarks There is partial support for Blit in wxPostScriptDC, under X. + */ + bool StretchBlit(wxCoord xdest, wxCoord ydest, wxCoord dstWidth, + wxCoord dstHeight, + wxDC* source, wxCoord xsrc, + wxCoord ysrc, + wxCoord srcWidth, + wxCoord srcHeight, + int logicalFunc = wxCOPY, + bool useMask = @false, + wxCoord xsrcMask = -1, + wxCoord ysrcMask = -1); +}; + + +/** + @class wxDCClipper + @wxheader{dc.h} + + wxDCClipper is a small helper class for setting a clipping region on a + wxDC and unsetting it automatically. An object of wxDCClipper + class is typically created on the stack so that it is automatically destroyed + when the object goes out of scope. A typical usage example: + + @code + void MyFunction(wxDC& dc) + { + wxDCClipper clip(rect); + ... drawing functions here are affected by clipping rect ... + } + + void OtherFunction() + { + wxDC dc; + MyFunction(dc); + ... drawing functions here are not affected by clipping rect ... + } + @endcode + + @library{wxcore} + @category{gdi} + + @seealso + wxDC::SetClippingRegion +*/ +class wxDCClipper +{ +public: + //@{ + /** + Sets the clipping region to the specified region @e r or rectangle specified + by either a single @e rect parameter or its position (@e x and @e y) + and size (@e w ad @e h). + + The clipping region is automatically unset when this object is destroyed. + */ + wxDCClipper(wxDC& dc, const wxRegion& r); + wxDCClipper(wxDC& dc, const wxRect& rect); + wxDCClipper(wxDC& dc, int x, int y, int w, int h); + //@} +}; diff --git a/interface/dcbuffer.h b/interface/dcbuffer.h new file mode 100644 index 0000000000..05d34e5ed8 --- /dev/null +++ b/interface/dcbuffer.h @@ -0,0 +1,187 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcbuffer.h +// Purpose: documentation for wxBufferedDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBufferedDC + @wxheader{dcbuffer.h} + + This class provides a simple way to avoid flicker: when drawing on it, + everything is in fact first drawn on an in-memory buffer (a + wxBitmap) and then copied to the screen, using the + associated wxDC, only once, when this object is destroyed. wxBufferedDC itself + is typically associated with wxClientDC, if you want to + use it in your @c EVT_PAINT handler, you should look at + wxBufferedPaintDC instead. + + When used like this, a valid @e dc must be specified in the constructor + while the @e buffer bitmap doesn't have to be explicitly provided, by + default this class will allocate the bitmap of required size itself. However + using a dedicated bitmap can speed up the redrawing process by eliminating the + repeated creation and destruction of a possibly big bitmap. Otherwise, + wxBufferedDC can be used in the same way as any other device context. + + There is another possible use for wxBufferedDC is to use it to maintain a + backing store for the window contents. In this case, the associated @e dc + may be @NULL but a valid backing store bitmap should be specified. + + Finally, please note that GTK+ 2.0 as well as OS X provide double buffering + themselves natively. You can either use wxWindow::IsDoubleBuffered + to determine whether you need to use buffering or not, or use + wxAutoBufferedPaintDC to avoid needless double + buffering on the systems which already do it automatically. + + @library{wxcore} + @category{dc} + + @seealso + wxDC, wxMemoryDC, wxBufferedPaintDC, wxAutoBufferedPaintDC +*/ +class wxBufferedDC : public wxMemoryDC +{ +public: + //@{ + /** + 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 @c Init() + must not be called after using them. + + @param dc + The underlying DC: everything drawn to this object will be + flushed to this DC when this object is destroyed. You may pass @NULL + in order to just initialize the buffer, and not flush it. + + @param area + The size of the bitmap to be used for buffering (this bitmap is + created internally when it is not given explicitly). + + @param buffer + Explicitly provided bitmap to be used for buffering: this is + the most efficient solution as the bitmap doesn't have to be recreated each + time but it also requires more memory as the bitmap is never freed. The bitmap + should have appropriate size, anything drawn outside of its bounds is clipped. + + @param style + wxBUFFER_CLIENT_AREA to indicate that just the client area of + the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the buffer + bitmap + covers the virtual area (in which case PrepareDC is automatically called for + the actual window + device context). + */ + wxBufferedDC(); + wxBufferedDC(wxDC * dc, const wxSize& area, + int style = wxBUFFER_CLIENT_AREA); + wxBufferedDC(wxDC * dc, wxBitmap& buffer, + int style = wxBUFFER_CLIENT_AREA); + //@} + + /** + Copies everything drawn on the DC so far to the underlying DC associated with + this object, if any. + */ + + + //@{ + /** + These functions initialize the object created using the default constructor. + Please see @ref ctor() "constructors documentation" for details. + */ + void Init(wxDC * dc, const wxSize& area, + int style = wxBUFFER_CLIENT_AREA); + void Init(wxDC * dc, wxBitmap& buffer, + int style = wxBUFFER_CLIENT_AREA); + //@} +}; + + +/** + @class wxAutoBufferedPaintDC + @wxheader{dcbuffer.h} + + This wxDC derivative can be used inside of an @c OnPaint() event handler to + achieve + double-buffered drawing. Just create an object of this class instead of + wxPaintDC + and make sure wxWindow::SetBackgroundStyle is called + with wxBG_STYLE_CUSTOM somewhere in the class initialization code, and that's + all you have + to do to (mostly) avoid flicker. + + The difference between wxBufferedPaintDC and this class, + is the lightweigthness - on platforms which have native double-buffering, + wxAutoBufferedPaintDC is simply + a typedef of wxPaintDC. Otherwise, it is a typedef of wxBufferedPaintDC. + + @library{wxbase} + @category{dc} + + @seealso + wxDC, wxBufferedPaintDC +*/ +class wxAutoBufferedPaintDC : public wxBufferedPaintDC +{ +public: + /** + Constructor. Pass a pointer to the window on which you wish to paint. + */ + wxAutoBufferedPaintDC(wxWindow * window); +}; + + +/** + @class wxBufferedPaintDC + @wxheader{dcbuffer.h} + + This is a subclass of wxBufferedDC which can be used + inside of an @c OnPaint() event handler. Just create an object of this class + instead + of wxPaintDC and make sure wxWindow::SetBackgroundStyle + is called with wxBG_STYLE_CUSTOM somewhere in the class initialization code, + and that's all + you have to do to (mostly) avoid flicker. The only thing to watch out for is + that if you are + using this class together with wxScrolledWindow, you probably + do @b not want to call wxScrolledWindow::PrepareDC on it as it + already does this internally for the real underlying wxPaintDC. + + @library{wxcore} + @category{dc} + + @seealso + wxDC, wxBufferedDC, wxAutoBufferedPaintDC +*/ +class wxBufferedPaintDC : public wxBufferedDC +{ +public: + //@{ + /** + As with @ref wxBufferedDC::ctor 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 @e 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). + */ + wxBufferedPaintDC(wxWindow * window, wxBitmap& buffer, + int style = wxBUFFER_CLIENT_AREA); + wxBufferedPaintDC(wxWindow * window, + int style = wxBUFFER_CLIENT_AREA); + //@} + + /** + Copies everything drawn on the DC so far to the window associated with this + object, using a wxPaintDC. + */ +}; diff --git a/interface/dcclient.h b/interface/dcclient.h new file mode 100644 index 0000000000..d88e6dd62e --- /dev/null +++ b/interface/dcclient.h @@ -0,0 +1,105 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcclient.h +// Purpose: documentation for wxPaintDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPaintDC + @wxheader{dcclient.h} + + A wxPaintDC must be constructed if an application wishes to paint on the + client area of a window from within an @b OnPaint event. + This should normally be constructed as a temporary stack object; don't store + a wxPaintDC object. If you have an OnPaint handler, you @e must create a + wxPaintDC + object within it even if you don't actually use it. + + Using wxPaintDC within OnPaint is important because it automatically + sets the clipping area to the damaged area of the window. Attempts to draw + outside this area do not appear. + + To draw on a window from outside @b OnPaint, construct a wxClientDC object. + + To draw on the whole window including decorations, construct a wxWindowDC object + (Windows only). + + @library{wxcore} + @category{dc} + + @seealso + wxDC, wxMemoryDC, wxPaintDC, wxWindowDC, wxScreenDC +*/ +class wxPaintDC : public wxWindowDC +{ +public: + /** + Constructor. Pass a pointer to the window on which you wish to paint. + */ + wxPaintDC(wxWindow* window); +}; + + +/** + @class wxClientDC + @wxheader{dcclient.h} + + A wxClientDC must be constructed if an application wishes to paint on the + client area of a window from outside an @b 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 @b OnPaint, construct a wxPaintDC object. + + To draw on the whole window including decorations, construct a wxWindowDC object + (Windows only). + + @library{wxcore} + @category{dc} + + @seealso + wxDC, wxMemoryDC, wxPaintDC, wxWindowDC, wxScreenDC +*/ +class wxClientDC : public wxWindowDC +{ +public: + /** + Constructor. Pass a pointer to the window on which you wish to paint. + */ + wxClientDC(wxWindow* window); +}; + + +/** + @class wxWindowDC + @wxheader{dcclient.h} + + A wxWindowDC must be constructed if an application wishes to paint on the + whole area of a window (client and decorations). + This should normally be constructed as a temporary stack object; don't store + a wxWindowDC object. + + To draw on a window from inside @b OnPaint, construct a wxPaintDC object. + + To draw on the client area of a window from outside @b OnPaint, construct a + wxClientDC object. + + To draw on the whole window including decorations, construct a wxWindowDC object + (Windows only). + + @library{wxcore} + @category{dc} + + @seealso + wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxScreenDC +*/ +class wxWindowDC : public wxDC +{ +public: + /** + Constructor. Pass a pointer to the window on which you wish to paint. + */ + wxWindowDC(wxWindow* window); +}; diff --git a/interface/dcmemory.h b/interface/dcmemory.h new file mode 100644 index 0000000000..d8c0520a6a --- /dev/null +++ b/interface/dcmemory.h @@ -0,0 +1,72 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcmemory.h +// Purpose: documentation for wxMemoryDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMemoryDC + @wxheader{dcmemory.h} + + A memory device context provides a means to draw graphics onto a bitmap. When + drawing in to a mono-bitmap, using @c wxWHITE, @c wxWHITE_PEN and + @c wxWHITE_BRUSH + will draw the background colour (i.e. 0) whereas all other colours will draw the + foreground colour (i.e. 1). + + @library{wxcore} + @category{dc} + + @seealso + wxBitmap, wxDC +*/ +class wxMemoryDC : public wxDC +{ +public: + //@{ + /** + Constructs a new memory device context and calls SelectObject() + with the given bitmap. + Use the wxDC::IsOk member to test whether the constructor was successful + in creating a usable device context. + */ + wxMemoryDC(); + wxMemoryDC(wxBitmap& bitmap); + //@} + + /** + Works exactly like SelectObjectAsSource() but + this is the function you should use when you select a bitmap because you want + to modify + it, e.g. drawing on this DC. + + Using SelectObjectAsSource() when modifying + the bitmap may incurr some problems related to wxBitmap being a reference + counted object + (see @ref overview_trefcount "reference counting overview"). + + Also, before using the updated bitmap data, make sure to select it out of + context first + (for example by selecting wxNullBitmap into the device context). + + @sa wxDC::DrawBitmap + */ + void SelectObject(wxBitmap& bitmap); + + /** + Selects the given bitmap into the device context, to use as the memory + bitmap. Selecting the bitmap into a memory DC allows you to draw into + the DC (and therefore the bitmap) and also to use wxDC::Blit to copy + the bitmap to a window. For this purpose, you may find wxDC::DrawIcon + easier to use instead. + + If the argument is wxNullBitmap (or some other uninitialised wxBitmap) the + current bitmap is + selected out of the device context, and the original bitmap restored, allowing + the current bitmap to + be destroyed safely. + */ + void SelectObjectAsSource(const wxBitmap& bitmap); +}; diff --git a/interface/dcmirror.h b/interface/dcmirror.h new file mode 100644 index 0000000000..eca8719544 --- /dev/null +++ b/interface/dcmirror.h @@ -0,0 +1,35 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcmirror.h +// Purpose: documentation for wxMirrorDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMirrorDC + @wxheader{dcmirror.h} + + wxMirrorDC is a simple wrapper class which is always associated with a real + wxDC object and either forwards all of its operations to it + without changes (no mirroring takes place) or exchanges @e x and @e y + coordinates which makes it possible to reuse the same code to draw a figure and + its mirror -- i.e. reflection related to the diagonal line x == y. + + wxMirrorDC has been added in wxWidgets version 2.5.0. + + @library{wxcore} + @category{dc} +*/ +class wxMirrorDC : public wxDC +{ +public: + /** + Creates a (maybe) mirrored DC associated with the real @e dc. Everything + drawn on wxMirrorDC will appear (and maybe mirrored) on @e dc. + + @e mirror specifies if we do mirror (if it is @true) or not (if it is + @false). + */ + wxMirrorDC(wxDC& dc, bool mirror); +}; diff --git a/interface/dcprint.h b/interface/dcprint.h new file mode 100644 index 0000000000..73524be66e --- /dev/null +++ b/interface/dcprint.h @@ -0,0 +1,55 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcprint.h +// Purpose: documentation for wxPrinterDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPrinterDC + @wxheader{dcprint.h} + + A printer device context is specific to MSW and Mac, and allows access to any + printer with a Windows or Macintosh driver. See wxDC for further + information on device contexts, and wxDC::GetSize for + advice on achieving the correct scaling for the page. + + @library{wxcore} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", wxDC +*/ +class wxPrinterDC : public wxDC +{ +public: + //@{ + /** + Constructor. With empty strings for the first three arguments, the default + printer dialog is + displayed. @e device indicates the type of printer and @e output + is an optional file for printing to. The @e driver parameter is + currently unused. Use the @e Ok member to test whether the + constructor was successful in creating a usable device context. + + This constructor is deprecated and retained only for backward compatibility. + */ + wxPrinterDC(const wxPrintData& printData); + wxPrinterDC(const wxString& driver, const wxString& device, + const wxString& output, + const bool interactive = @true, + int orientation = wxPORTRAIT); + //@} + + /** + Return the rectangle in device coordinates that corresponds to the full paper + area, including the nonprinting regions of the paper. The point (0,0) in device + coordinates is the top left corner of the page rectangle, which is the printable + area on MSW and Mac. The coordinates of the top left corner of the paper + rectangle will therefore have small negative values, while the bottom right + coordinates will be somewhat larger than the values returned by + wxDC::GetSize. + */ + wxRect wxPrinterDC::GetPaperRect(); +}; diff --git a/interface/dcps.h b/interface/dcps.h new file mode 100644 index 0000000000..aff85e7cb9 --- /dev/null +++ b/interface/dcps.h @@ -0,0 +1,145 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcps.h +// Purpose: documentation for wxPostScriptDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPostScriptDC + @wxheader{dcps.h} + + This defines the wxWidgets Encapsulated PostScript device context, + which can write PostScript files on any platform. See wxDC for + descriptions of the member functions. + + @library{wxbase} + @category{dc} +*/ +class wxPostScriptDC : public wxDC +{ +public: + //@{ + /** + Constructor. @e output is an optional file for printing to, and if + @e interactive is @true a dialog box will be displayed for adjusting + various parameters. @e parent is the parent of the printer dialog box. + + Use the @e Ok member to test whether the constructor was successful + in creating a usable device context. + + See @ref overview_printersettings "Printer settings" for functions to set and + get PostScript printing settings. + + This constructor and the global printer settings are now deprecated; + use the wxPrintData constructor instead. + */ + wxPostScriptDC(const wxPrintData& printData); + wxPostScriptDC(const wxString& output, + bool interactive = @true, + wxWindow * parent); + //@} + + /** + Return resolution used in PostScript output. See + SetResolution(). + */ + static int GetResolution(); + + /** + Set resolution (in pixels per inch) that will be used in PostScript + output. Default is 720ppi. + */ + static void SetResolution(int ppi); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Gets the printer command used to print a file. The default is @c lpr. +*/ +wxString wxGetPrinterCommand(); + +/** + Sets the printer command used to print a file. The default is @c lpr. +*/ +void wxSetPrinterCommand(const wxString& command); + +/** + Gets the orientation (PS_PORTRAIT or PS_LANDSCAPE). The default is PS_PORTRAIT. +*/ +int wxGetPrinterOrientation(); + +/** + Sets the additional options for the print command (e.g. specific printer). The + default is nothing. +*/ +void wxSetPrinterOptions(const wxString& options); + +/** + Gets the translation (from the top left corner) for PostScript output. The + default is 0.0, 0.0. +*/ +void wxGetPrinterTranslation(float * x, float * y); + +/** + Sets the scaling factor for PostScript output. The default is 1.0, 1.0. +*/ +void wxSetPrinterScaling(float x, float y); + +/** + Sets the orientation (PS_PORTRAIT or PS_LANDSCAPE). The default is PS_PORTRAIT. +*/ +void wxSetPrinterOrientation(int orientation); + +/** + Sets the printing mode controlling where output is sent (PS_PREVIEW, PS_FILE or + PS_PRINTER). + The default is PS_PREVIEW. +*/ +void wxSetPrinterMode(int mode); + +/** + Sets the PostScript output filename. +*/ +void wxSetPrinterFile(const wxString& filename); + +/** + Gets the PostScript output filename. +*/ +wxString wxGetPrinterFile(); + +/** + Gets the additional options for the print command (e.g. specific printer). The + default is nothing. +*/ +wxString wxGetPrinterOptions(); + +/** + Gets the command used to view a PostScript file. The default depends on the + platform. +*/ +wxString wxGetPrinterPreviewCommand(); + +/** + Gets the printing mode controlling where output is sent (PS_PREVIEW, PS_FILE or + PS_PRINTER). + The default is PS_PREVIEW. +*/ +int wxGetPrinterMode(); + +/** + Gets the scaling factor for PostScript output. The default is 1.0, 1.0. +*/ +void wxGetPrinterScaling(float * x, float * y); + +/** + Sets the command used to view a PostScript file. The default depends on the + platform. +*/ +void wxSetPrinterPreviewCommand(const wxString& command); + diff --git a/interface/dcscreen.h b/interface/dcscreen.h new file mode 100644 index 0000000000..185f306e8c --- /dev/null +++ b/interface/dcscreen.h @@ -0,0 +1,72 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcscreen.h +// Purpose: documentation for wxScreenDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxScreenDC + @wxheader{dcscreen.h} + + A wxScreenDC can be used to paint on the screen. + This should normally be constructed as a temporary stack object; don't store + a wxScreenDC object. + + @library{wxcore} + @category{dc} + + @seealso + wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxWindowDC +*/ +class wxScreenDC : public wxDC +{ +public: + /** + Constructor. + */ + wxScreenDC(); + + /** + Use this in conjunction with StartDrawingOnTop(). + + This function destroys the temporary window created to implement on-top drawing + (X only). + */ + bool EndDrawingOnTop(); + + //@{ + /** + Use this in conjunction with EndDrawingOnTop() to + ensure that drawing to the screen occurs on top of existing windows. Without + this, + some window systems (such as X) only allow drawing to take place underneath + other windows. + + By using the first form of this function, an application is specifying that + the area that will be drawn on coincides with the given window. + + By using the second form, an application can specify an area of the screen + which is to be drawn on. If @NULL is passed, the whole screen is available. + + It is recommended that an area of the screen is specified because with large + regions, + flickering effects are noticeable when destroying the temporary transparent + window used + to implement this feature. + + You might use this pair of functions when implementing a drag feature, for + example + as in the wxSplitterWindow implementation. + + @remarks This function is probably obsolete since the X implementations + allow drawing directly on the screen now. However, + the fact that this function allows the screen to be + refreshed afterwards, may be useful to some + applications. + */ + bool StartDrawingOnTop(wxWindow* window); + bool StartDrawingOnTop(wxRect* rect = @NULL); + //@} +}; diff --git a/interface/dcsvg.h b/interface/dcsvg.h new file mode 100644 index 0000000000..ecdd743dd9 --- /dev/null +++ b/interface/dcsvg.h @@ -0,0 +1,680 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcsvg.h +// Purpose: documentation for wxSVGFileDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSVGFileDC + @wxheader{dcsvg.h} + + A wxSVGFileDC is a @e device context onto which graphics and text can be drawn, + and the output + produced as a vector file, in the SVG format + (see W3C specifications). + This format can be read by a range of programs, including a Netscape plugin + (Adobe), full details + in the SVG Implementation and Resource Directory. + Vector formats may often be smaller than raster formats. + + The intention behind wxSVGFileDC is that it can be used to produce a file + corresponding + to the screen display context, wxSVGFileDC, by passing the wxSVGFileDC as a + parameter instead of a wxSVGFileDC. Thus the wxSVGFileDC is a write-only class. + + As the wxSVGFileDC is a vector format, raster operations like GetPixel are + unlikely to be supported. + However, the SVG specification allows for PNG format raster files to be + embedded in the SVG, and so + bitmaps, icons and blit operations into the wxSVGFileDC are supported. + + A more substantial SVG library (for reading and writing) is available at the + wxArt2D website. + + @library{wxcore} + @category{FIXME} + + @seealso + @b Members +*/ +class wxSVGFileDC : public wxDC +{ +public: + //@{ + /** + Constructors: + a filename @e f with default size 340x240 at 72.0 dots per inch (a frequent + screen resolution). + a filename @e f with size @e Width by @e Height at 72.0 dots per inch + a filename @e f with size @e Width by @e Height at @e dpi resolution. + */ + wxSVGFileDC(wxString f); + wxSVGFileDC(wxString f, int Width, int Height); + wxSVGFileDC(wxString f, int Width, int Height, float dpi); + //@} + + /** + Destructor. + */ + ~wxSVGFileDC(); + + /** + Does nothing + */ + + + /** + As wxDC: Copy from a source DC to this DC, specifying the destination + coordinates, size of area to copy, source DC, source coordinates, + logical function, whether to use a bitmap mask, and mask source position. + */ + bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, + wxCoord height, wxSVGFileDC* source, + wxCoord xsrc, wxCoord ysrc, + int logicalFunc = wxCOPY, + bool useMask = FALSE, + wxCoord xsrcMask = -1, + wxCoord ysrcMask = -1); + + /** + Adds the specified point to the bounding box which can be retrieved with + wxDC::MinX, wxDC::MaxX and + wxDC::MinY, wxDC::MaxY functions. + */ + void CalcBoundingBox(wxCoord x, wxCoord y); + + /** + This makes no sense in wxSVGFileDC and does nothing + */ + void Clear(); + + /** + Not Implemented + */ + void CrossHair(wxCoord x, wxCoord y); + + /** + Not Implemented + */ + void DestroyClippingRegion(); + + /** + Convert device X coordinate to logical coordinate, using the current + mapping mode. + */ + wxCoord DeviceToLogicalX(wxCoord x); + + /** + Convert device X coordinate to relative logical coordinate, using the current + mapping mode but ignoring the x axis orientation. + Use this function for converting a width, for example. + */ + wxCoord DeviceToLogicalXRel(wxCoord x); + + /** + Converts device Y coordinate to logical coordinate, using the current + mapping mode. + */ + wxCoord DeviceToLogicalY(wxCoord y); + + /** + Convert device Y coordinate to relative logical coordinate, using the current + mapping mode but ignoring the y axis orientation. + Use this function for converting a height, for example. + */ + wxCoord DeviceToLogicalYRel(wxCoord y); + + /** + Draws an arc of a circle, centred on (@e xc, yc), with starting point (@e x1, + y1) + and ending at (@e 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. + */ + void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, + wxCoord xc, wxCoord yc); + + /** + Draw a bitmap on the device context at the specified point. If @e 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 wxDC::SetTextForeground, + wxDC::SetTextBackground and wxMemoryDC. + */ + void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, + bool transparent); + + //@{ + /** + Draws a check mark inside the given rectangle. + */ + void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + void DrawCheckMark(const wxRect & rect); + //@} + + //@{ + /** + Draws a circle with the given centre and radius. + + @sa wxDC::DrawEllipse + */ + void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); + void DrawCircle(const wxPoint& pt, wxCoord radius); + //@} + + //@{ + /** + Draws an ellipse contained in the rectangle specified either with the given top + left corner and the given size or directly. The current pen is used for the + outline and the current brush for filling the shape. + + @sa wxDC::DrawCircle + */ + void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + void DrawEllipse(const wxPoint& pt, const wxSize& size); + void DrawEllipse(const wxRect& rect); + //@} + + /** + Draws an arc of an ellipse. The current pen is used for drawing the arc and + the current brush is used for drawing the pie. + + @e x and @e y specify the x and y coordinates of the upper-left corner of the + rectangle that contains + the ellipse. + + @e width and @e height specify the width and height of the rectangle that + contains + the ellipse. + + @e start and @e 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 @e start is equal to @e end, a + complete ellipse will be drawn. + */ + void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, + wxCoord height, + double start, + double end); + + /** + Draw an icon on the display (does nothing if the device context is PostScript). + This can be the simplest way of drawing bitmaps on a window. + */ + void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); + + /** + Draws a line from the first point to the second. The current pen is used + for drawing the line. + */ + void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); + + //@{ + /** + Draws lines using an array of @e points of size @e n, or list of + pointers to points, adding the optional offset coordinate. The current + pen is used for drawing the lines. The programmer is responsible for + deleting the list of points. + */ + void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, + wxCoord yoffset = 0); + void DrawLines(wxList * points, wxCoord xoffset = 0, + wxCoord yoffset = 0); + //@} + + /** + Draws a point using the current pen. + */ + void DrawPoint(wxCoord x, wxCoord y); + + //@{ + /** + Draws a filled polygon using an array of @e points of size @e n, + or list of pointers to points, adding the optional offset coordinate. + + The last argument specifies the fill rule: @b wxODDEVEN_RULE (the + default) or @b wxWINDING_RULE. + + The current pen is used for drawing the outline, and the current brush + for filling the shape. Using a transparent brush suppresses filling. + The programmer is responsible for deleting the list of points. + + Note that wxWindows automatically closes the first and last points. + */ + void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, + wxCoord yoffset = 0, + int fill_style = wxODDEVEN_RULE); + void DrawPolygon(wxList * points, wxCoord xoffset = 0, + wxCoord yoffset = 0, + int fill_style = wxODDEVEN_RULE); + //@} + + /** + Draws a rectangle with the given top left corner, and with the given + size. The current pen is used for the outline and the current brush + for filling the shape. + */ + void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + + /** + Draws the text rotated by @e angle degrees. + + The wxMSW wxDC and wxSVGFileDC rotate the text around slightly different + points, depending on the size of the font + */ + void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, + double angle); + + /** + Draws a rectangle with the given top left corner, and with the given + size. The corners are quarter-circles using the given radius. The + current pen is used for the outline and the current brush for filling + the shape. + + If @e radius is positive, the value is assumed to be the + radius of the rounded corner. If @e radius is negative, + the absolute value is assumed to be the @e proportion of the smallest + dimension of the rectangle. This means that the corner can be + a sensible size relative to the size of the rectangle, and also avoids + the strange effects X produces when the corners are too big for + the rectangle. + */ + void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, + wxCoord height, + double radius = 20); + + //@{ + /** + Draws a three-point spline using the current pen. + */ + void DrawSpline(wxList * points); + void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, + wxCoord y2, + wxCoord x3, + wxCoord y3); + //@} + + /** + Draws a text string at the specified point, using the current text font, + and the current text foreground and background colours. + + The coordinates refer to the top-left corner of the rectangle bounding + the string. See GetTextExtent() for how + to get the dimensions of a text string, which can be used to position the + text more precisely. + */ + void DrawText(const wxString& text, wxCoord x, wxCoord y); + + /** + Does nothing + */ + void EndDoc(); + + /** + Does nothing + */ + void EndDrawing(); + + /** + Does nothing + */ + void EndPage(); + + /** + Not implemented + */ + void FloodFill(wxCoord x, wxCoord y, const wxColour& colour, + int style=wxFLOOD_SURFACE); + + //@{ + /** + Gets the brush used for painting the background (see + wxSVGFileDC::SetBackground). + */ + wxBrush GetBackground(); + const wxBrush GetBackground(); + //@} + + /** + Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. + + @sa wxDC::SetBackgroundMode + */ + int GetBackgroundMode(); + + //@{ + /** + Gets the current brush (see wxSVGFileDC::SetBrush). + */ + wxBrush GetBrush(); + const wxBrush GetBrush(); + //@} + + /** + Gets the character height of the currently set font. + */ + wxCoord GetCharHeight(); + + /** + Gets the average character width of the currently set font. + */ + wxCoord GetCharWidth(); + + /** + Not implemented + */ + void GetClippingBox(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + + //@{ + /** + Gets the current font (see wxSVGFileDC::SetFont). + */ + wxFont GetFont(); + const wxFont GetFont(); + //@} + + /** + Gets the current logical function (see wxSVGFileDC::SetLogicalFunction). + */ + int GetLogicalFunction(); + + /** + Gets the @e mapping mode for the device context (see wxSVGFileDC::SetMapMode). + */ + int GetMapMode(); + + //@{ + /** + Gets the current pen (see wxSVGFileDC::SetPen). + */ + wxPen GetPen(); + const wxPen GetPen(); + //@} + + /** + Not implemented + */ + bool GetPixel(wxCoord x, wxCoord y, wxColour * colour); + + /** + For a Windows printer device context, this gets the horizontal and vertical + resolution. + */ + void GetSize(wxCoord * width, wxCoord * height); + + //@{ + /** + Gets the current text background colour (see wxSVGFileDC::SetTextBackground). + */ + wxColour GetTextBackground(); + const wxColour GetTextBackground(); + //@} + + /** + Gets the dimensions of the string using the currently selected font. + @e string is the text string to measure, @e w and @e h are + the total width and height respectively, @e descent is the + dimension from the baseline of the font to the bottom of the + descender, and @e externalLeading is any extra vertical space added + to the font by the font designer (usually is zero). + + The optional parameter @e 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, SetFont(). + */ + void GetTextExtent(const wxString& string, wxCoord * w, + wxCoord * h, + wxCoord * descent = @NULL, + wxCoord * externalLeading = @NULL, + wxFont * font = @NULL); + + //@{ + /** + Gets the current text foreground colour (see wxSVGFileDC::SetTextForeground). + */ + wxColour GetTextForeground(); + const wxColour GetTextForeground(); + //@} + + /** + Gets the current user scale factor (set by wxDC::SetUserScale). + */ + void GetUserScale(double x, double y); + + /** + Converts logical X coordinate to device coordinate, using the current + mapping mode. + */ + wxCoord LogicalToDeviceX(wxCoord x); + + /** + Converts logical X coordinate to relative device coordinate, using the current + mapping mode but ignoring the x axis orientation. + Use this for converting a width, for example. + */ + wxCoord LogicalToDeviceXRel(wxCoord x); + + /** + Converts logical Y coordinate to device coordinate, using the current + mapping mode. + */ + wxCoord LogicalToDeviceY(wxCoord y); + + /** + Converts logical Y coordinate to relative device coordinate, using the current + mapping mode but ignoring the y axis orientation. + Use this for converting a height, for example. + */ + wxCoord LogicalToDeviceYRel(wxCoord y); + + /** + Gets the maximum horizontal extent used in drawing commands so far. + */ +#define wxCoord MaxX() /* implementation is private */ + + /** + Gets the maximum vertical extent used in drawing commands so far. + */ +#define wxCoord MaxY() /* implementation is private */ + + /** + Gets the minimum horizontal extent used in drawing commands so far. + */ +#define wxCoord MinX() /* implementation is private */ + + /** + Gets the minimum vertical extent used in drawing commands so far. + */ +#define wxCoord MinY() /* implementation is private */ + + /** + Returns @true if the DC is ok to use; False values arise from being unable to + write the file + */ +#define bool Ok() /* implementation is private */ + + /** + Resets the bounding box: after a call to this function, the bounding box + doesn't contain anything. + + @sa wxDC::CalcBoundingBox + */ + void ResetBoundingBox(); + + /** + Sets the x and y axis orientation (i.e., the direction from lowest to + highest values on the axis). The default orientation is the natural + orientation, e.g. x axis from left to right and y axis from bottom up. + + @param xLeftRight + True to set the x axis orientation to the natural + left to right orientation, @false to invert it. + + @param yBottomUp + True to set the y axis orientation to the natural + bottom up orientation, @false to invert it. + */ + void SetAxisOrientation(bool xLeftRight, bool yBottomUp); + + /** + Sets the current background brush for the DC. + */ + void SetBackground(const wxBrush& brush); + + /** + @e mode may be one of wxSOLID and wxTRANSPARENT. This setting determines + whether text will be drawn with a background colour or not. + */ + void SetBackgroundMode(int mode); + + /** + Sets the current brush for the DC. + + If the argument is wxNullBrush, the current brush is selected out of the device + context, and the original brush restored, allowing the current brush to + be destroyed safely. + + See also wxBrush. + + See also wxMemoryDC for the interpretation of colours + when drawing into a monochrome bitmap. + */ + void SetBrush(const wxBrush& brush); + + //@{ + /** + Not implemented + */ + void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + void SetClippingRegion(const wxPoint& pt, const wxSize& sz); + void SetClippingRegion(const wxRect& rect); + void SetClippingRegion(const wxRegion& region); + //@} + + /** + Sets the device origin (i.e., the origin in pixels after scaling has been + applied). + + This function may be useful in Windows printing + operations for placing a graphic on a page. + */ + void SetDeviceOrigin(wxCoord x, wxCoord y); + + /** + Sets the current font for the DC. It must be a valid font, in particular you + should not pass @c wxNullFont to this method. + + See also wxFont. + */ + void SetFont(const wxFont& font); + + /** + Only wxCOPY is avalaible; trying to set one of the othe values will fail + */ + void SetLogicalFunction(int function); + + /** + The @e 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 @e user scale (see + wxSVGFileDC::SetUserScale) scales the text appropriately. In + Windows, scaleable TrueType fonts are always used; in X, results depend + on availability of fonts, but usually a reasonable match is found. + + Note that the coordinate origin should ideally be selectable, but for + now is always at the top left of the screen/printer. + + Drawing to a Windows printer device context under UNIX + uses the current mapping mode, but mapping mode is currently ignored for + PostScript output. + + The mapping mode can be one of the following: + + wxMM_TWIPS + + + Each logical unit is 1/20 of a point, or 1/1440 of + an inch. + + wxMM_POINTS + + + Each logical unit is a point, or 1/72 of an inch. + + wxMM_METRIC + + + Each logical unit is 1 mm. + + wxMM_LOMETRIC + + + Each logical unit is 1/10 of a mm. + + wxMM_TEXT + + + Each logical unit is 1 pixel. + */ + void SetMapMode(int int); + + /** + Not implemented + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the current pen for the DC. + + If the argument is wxNullPen, the current pen is selected out of the device + context, and the original pen restored. + + See also wxMemoryDC for the interpretation of colours + when drawing into a monochrome bitmap. + */ + void SetPen(const wxPen& pen); + + /** + Sets the current text background colour for the DC. + */ + void SetTextBackground(const wxColour& colour); + + /** + Sets the current text foreground colour for the DC. + + See also wxMemoryDC for the interpretation of colours + when drawing into a monochrome bitmap. + */ + void SetTextForeground(const wxColour& colour); + + /** + Sets the user scaling factor, useful for applications which require + 'zooming'. + */ + void SetUserScale(double xScale, double yScale); + + /** + Does nothing + */ + bool StartDoc(const wxString& message); +}; diff --git a/interface/dde.h b/interface/dde.h new file mode 100644 index 0000000000..5ce037a88e --- /dev/null +++ b/interface/dde.h @@ -0,0 +1,337 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dde.h +// Purpose: documentation for wxDDEConnection class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDDEConnection + @wxheader{dde.h} + + A wxDDEConnection object represents the connection between a client and a + server. It can be created by making a connection using a + wxDDEClient object, or by the acceptance of a connection by a + wxDDEServer object. The bulk of a DDE (Dynamic Data Exchange) + conversation is controlled by + calling members in a @b wxDDEConnection object or by overriding its + members. + + An application should normally derive a new connection class from + wxDDEConnection, in order to override the communication event handlers + to do something interesting. + + This DDE-based implementation is available on Windows only, + but a platform-independent, socket-based version + of this API is available using wxTCPConnection. + + @library{wxbase} + @category{FIXME} + + @seealso + wxDDEClient, wxDDEServer, @ref overview_ipcoverview "Interprocess + communications overview" +*/ +class wxDDEConnection : public wxObject +{ +public: + //@{ + /** + Constructs a connection object. If no user-defined connection object is + to be derived from wxDDEConnection, then the constructor should not be + called directly, since the default connection object will be provided on + requesting (or accepting) a connection. However, if the user defines his + or her own derived connection object, the wxDDEServer::OnAcceptConnection + and/or wxDDEClient::OnMakeConnection members should be replaced by + functions which construct the new connection object. 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. + */ + wxDDEConnection(); + wxDDEConnection(void* buffer, size_t size); + //@} + + //@{ + /** + Called by the server application to advise the client of a change in + the data associated with the given item. Causes the client + connection's OnAdvise() + member to be called. Returns @true if successful. + */ + bool Advise(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Advise(const wxString& item, const char* data); + bool Advise(const wxString& item, const wchar_t* data); + bool Advise(const wxString& item, const wxString data); + //@} + + /** + Called by the client or server application to disconnect from the other + program; it causes the OnDisconnect() message + to be sent to the corresponding connection object in the other + program. The default behaviour of @b OnDisconnect is to delete the + connection, but the calling application must explicitly delete its + side of the connection having called @b Disconnect. Returns @true if + successful. + */ + bool Disconnect(); + + //@{ + /** + Called by the client application to execute a command on the server. Can + also be used to transfer arbitrary data to the server (similar + to Poke() in that respect). Causes the + server connection's OnExecute() member to be + called. Returns @true if successful. + */ + bool Execute(const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Execute(const char* data); + bool Execute(const wchar_t* data); + bool Execute(const wxString data); + //@} + + /** + Message sent to the client application when the server notifies it of a + change in the data associated with the given item. + */ + virtual bool OnAdvise(const wxString& topic, + const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the client or server application when the other + application notifies it to delete the connection. Default behaviour is + to delete the connection object. + */ + virtual bool OnDisconnect(); + + /** + Message sent to the server application when the client notifies it to + execute the given data. Note that there is no item associated with + this message. + */ + virtual bool OnExecute(const wxString& topic, const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the server application when the client notifies it to + accept the given data. + */ + virtual bool OnPoke(const wxString& topic, const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the server application when the client + calls Request(). The server + should respond by returning a character string from @b OnRequest, + or @NULL to indicate no data. + */ + virtual const void* OnRequest(const wxString& topic, + const wxString& item, + size_t * size, + wxIPCFormat format); + + /** + Message sent to the server application by the client, when the client + wishes to start an 'advise loop' for the given topic and item. The + server can refuse to participate by returning @false. + */ + virtual bool OnStartAdvise(const wxString& topic, + const wxString& item); + + /** + Message sent to the server application by the client, when the client + wishes to stop an 'advise loop' for the given topic and item. The + server can refuse to stop the advise loop by returning @false, although + this doesn't have much meaning in practice. + */ + virtual bool OnStopAdvise(const wxString& topic, + const wxString& item); + + //@{ + /** + Called by the client application to poke data into the server. Can be + used to transfer arbitrary data to the server. Causes the server + connection's OnPoke() member + to be called. Returns @true if successful. + */ + bool Poke(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Poke(const wxString& item, const char* data); + bool Poke(const wxString& item, const wchar_t* data); + bool Poke(const wxString& item, const wxString data); + //@} + + /** + Called by the client application to request data from the server. Causes + the server connection's OnRequest() member to be called. Returns a + character string (actually a pointer to the connection's buffer) if + successful, @NULL otherwise. + */ + const void* Request(const wxString& item, size_t * size, + wxIPCFormat format = wxIPC_TEXT); + + /** + Called by the client application to ask if an advise loop can be started + with the server. Causes the server connection's OnStartAdvise() + member to be called. Returns @true if the server okays it, @false + otherwise. + */ + bool StartAdvise(const wxString& item); + + /** + Called by the client application to ask if an advise loop can be + stopped. Causes the server connection's OnStopAdvise() member + to be called. Returns @true if the server okays it, @false otherwise. + */ + bool StopAdvise(const wxString& item); +}; + + +/** + @class wxDDEClient + @wxheader{dde.h} + + A wxDDEClient object represents the client part of a client-server DDE + (Dynamic Data Exchange) conversation. + + To create a client which can communicate with a suitable server, + you need to derive a class from wxDDEConnection and another from wxDDEClient. + The custom wxDDEConnection class will intercept communications in + a 'conversation' with a server, and the custom wxDDEServer is required + so that a user-overridden 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. + + @library{wxbase} + @category{FIXME} + + @seealso + wxDDEServer, wxDDEConnection, @ref overview_ipcoverview "Interprocess + communications overview" +*/ +class wxDDEClient : public wxObject +{ +public: + /** + Constructs a client object. + */ + wxDDEClient(); + + /** + Tries to make a connection with a server specified by the host + (machine name under UNIX, ignored under Windows), service name (must + contain an integer port number under UNIX), and topic string. If the + server allows a connection, a wxDDEConnection object will be returned. + The type of wxDDEConnection returned can be altered by overriding + the OnMakeConnection() member to return your own + derived connection object. + */ + wxConnectionBase * MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); + + /** + The type of wxDDEConnection returned from a MakeConnection() call can + be altered by deriving the @b OnMakeConnection member to return your + own derived connection object. By default, a wxDDEConnection + object is returned. + + The advantage of deriving your own connection class is that it will + enable you to intercept messages initiated by the server, such + as wxDDEConnection::OnAdvise. You may also want to + store application-specific data in instances of the new class. + */ + wxConnectionBase * OnMakeConnection(); + + /** + Returns @true if this is a valid host name, @false otherwise. This always + returns @true under MS Windows. + */ + bool ValidHost(const wxString& host); +}; + + +/** + @class wxDDEServer + @wxheader{dde.h} + + A wxDDEServer object represents the server part of a client-server DDE + (Dynamic Data Exchange) conversation. + + This DDE-based implementation is + available on Windows only, but a platform-independent, socket-based version + of this API is available using wxTCPServer. + + @library{wxbase} + @category{FIXME} + + @seealso + wxDDEClient, wxDDEConnection, @ref overview_ipcoverview "IPC overview" +*/ +class wxDDEServer +{ +public: + /** + Constructs a server object. + */ + wxDDEServer(); + + /** + Registers the server using the given service name. Under UNIX, the + string must contain an integer id which is used as an Internet port + number. @false is returned if the call failed (for example, the port + number is already in use). + */ + bool Create(const wxString& service); + + /** + When a client calls @b MakeConnection, the server receives the + message and this member is called. The application should derive a + member to intercept this message and return a connection object of + either the standard 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. + */ + virtual wxConnectionBase * OnAcceptConnection(const wxString& topic); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Called when wxWidgets exits, to clean up the DDE system. This no longer needs + to be + called by the application. + + See also wxDDEInitialize. +*/ +void wxDDECleanUp(); + +/** + Initializes the DDE system. May be called multiple times without harm. + + This no longer needs to be called by the application: it will be called + by wxWidgets if necessary. + + See also wxDDEServer, wxDDEClient, wxDDEConnection, + wxDDECleanUp. +*/ +void wxDDEInitialize(); + diff --git a/interface/debug.h b/interface/debug.h new file mode 100644 index 0000000000..10b70af284 --- /dev/null +++ b/interface/debug.h @@ -0,0 +1,164 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: debug.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + Will always generate an assert error if this code is reached (in debug mode). + + See also: wxFAIL_MSG +*/ +#define wxFAIL() /* implementation is private */ + + + /** + This function is called whenever one of debugging macros fails (i.e. condition + is @false in an assertion). It is only defined in the debug mode, in release + builds the wxCHECK failures don't result in anything. + + To override the default behaviour in the debug builds which is to show the user + a dialog asking whether he wants to abort the program, continue or continue + ignoring any subsequent assert failures, you may override + wxApp::OnAssertFailure which is called by this function if + the global application object exists. +*/ +void wxOnAssert(const char * fileName, int lineNumber, + const char * func, + const char * cond, + const char * msg = @NULL); + +/** + In debug mode (when @c __WXDEBUG__ is defined) this function generates a + debugger exception meaning that the control is passed to the debugger if one is + attached to the process. Otherwise the program just terminates abnormally. + + In release mode this function does nothing. +*/ +void wxTrap(); + +/** + Will always generate an assert error with specified message if this code is + reached (in debug mode). + + This macro is useful for marking unreachable" code areas, for example + it may be used in the "default:" branch of a switch statement if all possible + cases are processed above. + + @sa wxFAIL +*/ +#define wxFAIL_MSG(msg) /* implementation is private */ + +/** + Checks that the condition is @true, returns with the given return value if not + (FAILs in debug mode). + This check is done even in release mode. +*/ +#define wxCHECK(condition, retValue) /* implementation is private */ + +/** + This macro results in a + @ref overview_wxcompiletimeassert "compile time assertion failure" if the size + of the given type @e type is less than @e size bits. + + You may use it like this, for example: + @code + // we rely on the int being able to hold values up to 2^32 + wxASSERT_MIN_BITSIZE(int, 32); + + // can't work with the platforms using UTF-8 for wchar_t + wxASSERT_MIN_BITSIZE(wchar_t, 16); + @endcode +*/ +#define wxASSERT_MIN_BITSIZE(type, size) /* implementation is private */ + +/** + Assert macro with message. An error message will be generated if the condition + is @false. + + @sa wxASSERT, wxCOMPILE_TIME_ASSERT +*/ +#define wxASSERT_MSG(condition, msg) /* implementation is private */ + +/** + This is the same as wxCHECK2, but + wxFAIL_MSG with the specified @e msg is called + instead of wxFAIL() if the @e condition is @false. +*/ +#define wxCHECK2(condition, operation, msg) /* implementation is private */ + +/** + Assert macro. An error message will be generated if the condition is @false in + debug mode, but nothing will be done in the release build. + + Please note that the condition in wxASSERT() should have no side effects + because it will not be executed in release mode at all. + + @sa wxASSERT_MSG, wxCOMPILE_TIME_ASSERT +*/ +#define wxASSERT(condition) /* implementation is private */ + +/** + Checks that the condition is @true, and returns if not (FAILs with given error + message in debug mode). This check is done even in release mode. + + This macro should be used in void functions instead of + wxCHECK_MSG. +*/ +#define wxCHECK_RET(condition, msg) /* implementation is private */ + +/** + Checks that the condition is @true and wxFAIL and execute + @e operation if it is not. This is a generalisation of + wxCHECK and may be used when something else than just + returning from the function must be done when the @e condition is @false. + + This check is done even in release mode. +*/ +#define wxCHECK2(condition, operation) /* implementation is private */ + +/** + This macro is identical to wxCOMPILE_TIME_ASSERT2 + except that it allows you to specify a unique @e name for the struct + internally defined by this macro to avoid getting the compilation errors + described above. +*/ +#define wxCOMPILE_TIME_ASSERT(condition, msg, name) /* implementation is private */ + +/** + Checks that the condition is @true, returns with the given return value if not + (FAILs in debug mode). + This check is done even in release mode. + + This macro may be only used in non-void functions, see also + wxCHECK_RET. +*/ +#define wxCHECK_MSG(condition, retValue, msg) /* implementation is private */ + +/** + Using @c wxCOMPILE_TIME_ASSERT results in a compilation error if the + specified @e condition is @false. The compiler error message should include + the @e msg identifier - please note that it must be a valid C++ identifier + and not a string unlike in the other cases. + + This macro is mostly useful for testing the expressions involving the + @c sizeof operator as they can't be tested by the preprocessor but it is + sometimes desirable to test them at the compile time. + + Note that this macro internally declares a struct whose name it tries to make + unique by using the @c __LINE__ in it but it may still not work if you + use it on the same line in two different source files. In this case you may + either change the line in which either of them appears on or use the + wxCOMPILE_TIME_ASSERT2 macro. + + Also note that Microsoft Visual C++ has a bug which results in compiler errors + if you use this macro with 'Program Database For Edit And Continue' + (@c /ZI) option, so you shouldn't use it ('Program Database' + (@c /Zi) is ok though) for the code making use of this macro. + + @sa wxASSERT_MSG, wxASSERT_MIN_BITSIZE +*/ +#define wxCOMPILE_TIME_ASSERT(condition, msg) /* implementation is private */ + diff --git a/interface/debugrpt.h b/interface/debugrpt.h new file mode 100644 index 0000000000..707250c6d3 --- /dev/null +++ b/interface/debugrpt.h @@ -0,0 +1,331 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: debugrpt.h +// Purpose: documentation for wxDebugReportPreview class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDebugReportPreview + @wxheader{debugrpt.h} + + This class presents the debug report to the user and allows him to veto report + entirely or remove some parts of it. Although not mandatory, using this class + is strongly recommended as data included in the debug report might contain + sensitive private information and the user should be notified about it as well + as having a possibility to examine the data which had been gathered to check + whether this is effectively the case and discard the debug report if it is. + + wxDebugReportPreview is an abstract base class, currently the only concrete + class deriving from it is + wxDebugReportPreviewStd. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReportPreview +{ +public: + /** + Trivial default constructor. + */ + wxDebugReportPreview(); + + /** + dtor is trivial as well but should be virtual for a base class + */ + ~wxDebugReportPreview(); + + /** + Present the report to the user and allow him to modify it by removing some or + all of the files and, potentially, adding some notes. Return @true if the + report should be processed or @false if the user chose to cancel report + generation or removed all files from it. + */ + bool Show(wxDebugReport& dbgrpt); +}; + + +/** + @class wxDebugReportCompress + @wxheader{debugrpt.h} + + wxDebugReportCompress is a wxDebugReport which + compresses all the files in this debug report into a single .ZIP file in its + @c @e Process() function. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReportCompress : public wxDebugReport +{ +public: + /** + Default constructor does nothing special. + */ + wxDebugReportCompress(); + + /** + Returns the full path of the compressed file (empty if creation failed). + */ + const wxString GetCompressedFileName(); +}; + + +/** + @class wxDebugReport + @wxheader{debugrpt.h} + + wxDebugReport is used to generate a debug report, containing information about + the program current state. It is usually used from + wxApp::OnFatalException as shown in the + 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. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReport +{ +public: + /** + The constructor creates a temporary directory where the files that will + be included in the report are created. Use + IsOk() to check for errors. + */ + wxDebugReport(); + + /** + The destructor normally destroys the temporary directory created in the + constructor + with all the files it contains. Call Reset() to + prevent this from happening. + */ + ~wxDebugReport(); + + /** + Adds all available information to the report. Currently this includes a + text (XML) file describing the process context and, under Win32, a minidump + file. + */ + void AddAll(Context context = Context_Exception); + + /** + Add an XML file containing the current or exception context and the + stack trace. + */ + bool AddContext(Context ctx); + + /** + The same as @ref addcontext() AddContext(Context_Current). + */ + bool AddCurrentContext(); + + /** + The same as @ref adddump() AddDump(Context_Current). + */ + bool AddCurrentDump(); + + /** + Adds the minidump file to the debug report. + + Minidumps are only available under recent Win32 versions (@c dbghlp32.dll + can be installed under older systems to make minidumps available). + */ + bool AddDump(Context ctx); + + /** + The same as @ref addcontext() AddContext(Context_Exception). + */ + bool AddExceptionContext(); + + /** + The same as @ref adddump() AddDump(Context_Exception). + */ + bool AddExceptionDump(); + + /** + Add another file to the report. If @e 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 + + @e description only exists to be displayed to the user in the report summary + shown by wxDebugReportPreview. + */ + void AddFile(const wxString& filename, + const wxString& description); + + /** + This is a convenient wrapper around AddFile(). It + creates the file with the given @e name and writes @e text to it, then + adds the file to the report. The @e filename shouldn't contain the path. + + Returns @true if file could be added successfully, @false if an IO error + occurred. + */ + bool AddText(const wxString& filename, const wxString& text, + const wxString& description); + + /** + This function may be overridden to add arbitrary custom context to the XML + context file created by AddContext(). By + default, it does nothing. + */ + void DoAddCustomContext(wxXmlNode * nodeRoot); + + /** + This function may be overridden to modify the contents of the exception tag in + the XML context file. + */ + bool DoAddExceptionInfo(wxXmlNode* nodeContext); + + /** + This function may be overridden to modify the contents of the modules tag in + the XML context file. + */ + bool DoAddLoadedModules(wxXmlNode* nodeModules); + + /** + This function may be overridden to modify the contents of the system tag in + the XML context file. + */ + bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo); + + /** + 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(). + */ + const wxString GetDirectory(); + + /** + Retrieves the name (relative to + wxDebugReport::GetDirectory) and the description of the + file with the given index. If @e n is greater than or equal to the number of + filse, @false is returned. + */ + bool GetFile(size_t n, wxString* name, wxString* desc); + + /** + Gets the current number files in this report. + */ + size_t GetFilesCount(); + + /** + Gets the name used as a base name for various files, by default + wxApp::GetAppName is used. + */ + wxString GetReportName(); + + /** + Returns @true if the object was successfully initialized. If this method + returns + @false the report can't be used. + */ +#define bool IsOk() /* implementation is private */ + + /** + Processes this report: the base class simply notifies the user that the + report has been generated. This is usually not enough -- instead you + should override this method to do something more useful to you. + */ + bool Process(); + + /** + Removes the file from report: this is used by + wxDebugReportPreview to allow the user to + remove files potentially containing private information from the report. + */ + void RemoveFile(const wxString& name); + + /** + Resets the directory name we use. The object can't be used any more after + this as it becomes uninitialized and invalid. + */ + void Reset(); +}; + + +/** + @class wxDebugReportPreviewStd + @wxheader{debugrpt.h} + + wxDebugReportPreviewStd is a standard debug report preview window. It displays + a GUIdialog allowing the user to examine the contents of a debug report, remove + files from and add notes to it. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReportPreviewStd : public wxDebugReportPreview +{ +public: + /** + Trivial default constructor. + */ + wxDebugReportPreviewStd(); + + /** + Show the dialog, see + wxDebugReportPreview::Show for more + information. + */ + bool Show(wxDebugReport& dbgrpt); +}; + + +/** + @class wxDebugReportUpload + @wxheader{debugrpt.h} + + This class is used to upload a compressed file using HTTP POST request. As this + class derives from wxDebugReportCompress, before upload the report is + compressed in a single .ZIP file. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReportUpload : public wxDebugReportCompress +{ +public: + /** + ) + + This class will upload the compressed file created by its base class to an HTML + multipart/form-data form at the specified address. The @e url is the upload + page address, @e input is the name of the @c "type=file" control on + the form used for the file name and @e action is the value of the form + action field. The report is uploaded using @c @e curl program which + should be available, the @e curl parameter may be used to specify the full + path to it. + */ + wxDebugReportUpload(const wxString& url, const wxString& input, + const wxString& action); + + /** + ) + + This function may be overridden in a derived class to show the output from + curl: this may be an HTML page or anything else that the server returned. + Value returned by this function becomes the return value of + wxDebugReport::Process. + */ + bool OnServerReply(); +}; diff --git a/interface/defs.h b/interface/defs.h new file mode 100644 index 0000000000..ee12d36911 --- /dev/null +++ b/interface/defs.h @@ -0,0 +1,149 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: defs.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + //@{ +/** + These macros will swap the bytes of the @e value variable from little + endian to big endian or vice versa unconditionally, i.e. independently of the + current platform. +*/ +wxInt32 wxINT32_SWAP_ALWAYS(wxInt32 value); + wxUint32 wxUINT32_SWAP_ALWAYS(wxUint32 value); + wxInt16 wxINT16_SWAP_ALWAYS(wxInt16 value); + wxUint16 wxUINT16_SWAP_ALWAYS(wxUint16 value); +//@} + + + //@{ +/** + This macro will swap the bytes of the @e value variable from little + endian to big endian or vice versa if the program is compiled on a + little-endian architecture (such as Intel PCs). If the program has + been compiled on a big-endian architecture, the value will be unchanged. + + Use these macros to read data from and write data to a file that stores + data in big-endian format. +*/ +wxInt32 wxINT32_SWAP_ON_LE(wxInt32 value); + wxUint32 wxUINT32_SWAP_ON_LE(wxUint32 value); + wxInt16 wxINT16_SWAP_ON_LE(wxInt16 value); + wxUint16 wxUINT16_SWAP_ON_LE(wxUint16 value); +//@} + +/** + This macro is similar to wxDEPRECATED but can be used + to not only declare the function @e func as deprecated but to also provide + its (inline) implementation @e body. + + It can be used as following: + + @code + class wxFoo + { + public: + // OldMethod() is deprecated, use NewMethod() instead + void NewMethod(); + wxDEPRECATED_INLINE( void OldMethod(), NewMethod() ); + }; + @endcode +*/ +#define wxDEPRECATED_INLINE(func, body) /* implementation is private */ + +/** + @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if + the compiler supports it or nothing otherwise. Thus, it can be used even in the + code which might have to be compiled with an old compiler without support for + this language feature but still take advantage of it when it is available. +*/ + + +/** + GNU C++ compiler gives a warning for any class whose destructor is private + unless it has a friend. This warning may sometimes be useful but it doesn't + make sense for reference counted class which always delete themselves (hence + destructor should be private) but don't necessarily have any friends, so this + macro is provided to disable the warning in such case. The @e name parameter + should be the name of the class but is only used to construct a unique friend + class name internally. Example of using the macro: + @code + class RefCounted + { + public: + RefCounted() { m_nRef = 1; } + void IncRef() { m_nRef++ ; } + void DecRef() { if ( !--m_nRef ) delete this; } + + private: + ~RefCounted() { } + + wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted) + }; + @endcode + + Notice that there should be no semicolon after this macro. +*/ +#define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name) /* implementation is private */ + +//@{ +/** + This macro will swap the bytes of the @e value variable from little + endian to big endian or vice versa if the program is compiled on a + big-endian architecture (such as Sun work stations). If the program has + been compiled on a little-endian architecture, the value will be unchanged. + + Use these macros to read data from and write data to a file that stores + data in little-endian (for example Intel i386) format. +*/ +wxInt32 wxINT32_SWAP_ON_BE(wxInt32 value); + wxUint32 wxUINT32_SWAP_ON_BE(wxUint32 value); + wxInt16 wxINT16_SWAP_ON_BE(wxInt16 value); + wxUint16 wxUINT16_SWAP_ON_BE(wxUint16 value); +//@} + +/** + This macro can be used around a function declaration to generate warnings + indicating that this function is deprecated (i.e. obsolete and planned to be + removed in the future) when it is used. Only Visual C++ 7 and higher and g++ + compilers currently support this functionality. + + Example of use: + + @code + // old function, use wxString version instead + wxDEPRECATED( void wxGetSomething(char *buf, size_t len) ); + + // ... + wxString wxGetSomething(); + @endcode +*/ + + +/** + This macro is the same as the standard C99 @c va_copy for the compilers + which support it or its replacement for those that don't. It must be used to + preserve the value of a @c va_list object if you need to use it after + passing it to another function because it can be modified by the latter. + + As with @c va_start, each call to @c wxVaCopy must have a matching + @c va_end. +*/ +void wxVaCopy(va_list argptrDst, va_list argptrSrc); + +/** + This is a special version of wxDEPRECATED macro which + only does something when the deprecated function is used from the code outside + wxWidgets itself but doesn't generate warnings when it is used from wxWidgets. + It is used with the virtual functions which are called by the library itself -- + even if such function is deprecated the library still has to call it to ensure + that the existing code overriding it continues to work, but the use of this + macro ensures that a deprecation warning will be generated if this function is + used from the user code or, in case of Visual C++, even when it is simply + overridden. +*/ + + diff --git a/interface/dialog.h b/interface/dialog.h new file mode 100644 index 0000000000..002b088c4e --- /dev/null +++ b/interface/dialog.h @@ -0,0 +1,559 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dialog.h +// Purpose: documentation for wxDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDialog + @wxheader{dialog.h} + + A dialog box is a window with a title bar and sometimes a system menu, which + can be moved around the screen. It can contain controls and other windows and + is often used to allow the user to make some choice or to answer a question. + + Dialogs can be made scrollable, automatically: please see @ref + overview_autoscrollingdialogs "Automatic scrolling dialogs" for further details. + + @beginStyleTable + @style{wxCAPTION}: + Puts a caption on the dialog box. + @style{wxDEFAULT_DIALOG_STYLE}: + Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and + wxSYSTEM_MENU (the last one is not used under Unix) + @style{wxRESIZE_BORDER}: + Display a resizeable frame around the window. + @style{wxSYSTEM_MENU}: + Display a system menu. + @style{wxCLOSE_BOX}: + Displays a close box on the frame. + @style{wxMAXIMIZE_BOX}: + Displays a maximize box on the dialog. + @style{wxMINIMIZE_BOX}: + Displays a minimize box on the dialog. + @style{wxTHICK_FRAME}: + Display a thick frame around the window. + @style{wxSTAY_ON_TOP}: + The dialog stays on top of all other windows. + @style{wxNO_3D}: + Under Windows, specifies that the child controls should not have 3D + borders unless specified in the control. + @style{wxDIALOG_NO_PARENT}: + By default, a dialog created with a @NULL parent window will be + given the application's top level window as parent. Use this style + to prevent this from happening and create an orphan dialog. This is + not recommended for modal dialogs. + @style{wxDIALOG_EX_CONTEXTHELP}: + Under Windows, puts a query button on the caption. When pressed, + Windows will go into a context-sensitive help mode and wxWidgets + will send a wxEVT_HELP event if the user clicked on an application + window. Note that this is an extended style and must be set by + calling SetExtraStyle before Create is called (two-step + construction). + @style{wxDIALOG_EX_METAL}: + On Mac OS X, frames with this style will be shown with a metallic + look. This is an extra style. + @endStyleTable + + @library{wxcore} + @category{cmndlg} + + @seealso + @ref overview_wxdialogoverview "wxDialog overview", wxFrame, @ref + overview_validatoroverview "Validator overview" +*/ +class wxDialog : public wxTopLevelWindow +{ +public: + //@{ + /** + Constructor. + + @param parent + Can be @NULL, a frame or another dialog box. + + @param id + An identifier for the dialog. A value of -1 is taken to mean a default. + + @param title + The title of the dialog. + + @param pos + The dialog position. The value wxDefaultPosition indicates a default position, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param size + The dialog size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param style + The window style. See wxDialog. + + @param name + Used to associate a name with the window, + allowing the application user to set Motif resource values for + individual dialog boxes. + + @sa Create() + */ + wxDialog(); + wxDialog(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, + const wxString& name = "dialogBox"); + //@} + + /** + Destructor. Deletes any child windows before deleting the physical window. + */ + ~wxDialog(); + + /** + Adds an identifier to be regarded as a main button for the non-scrolling area + of a dialog. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + void AddMainButtonId(wxWindowID id); + + /** + Returns @true if this dialog can and should perform layout adaptation using + DoLayoutAdaptation(), usually if + the dialog is too large to fit on the display. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + bool CanDoLayoutAdapation(); + + /** + Centres the dialog box on the display. + + @param direction + May be wxHORIZONTAL, wxVERTICAL or wxBOTH. + */ + void Centre(int direction = wxBOTH); + + /** + Used for two-step dialog box construction. See wxDialog() + for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, + const wxString& name = "dialogBox"); + + /** + Creates a sizer with standard buttons. @e flags is a bit list + of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, + wxHELP, wxNO_DEFAULT. + + The sizer lays out the buttons in a manner appropriate to the platform. + + This function uses CreateStdDialogButtonSizer() + internally for most platforms but doesn't create the sizer at all for the + platforms with hardware buttons (such as smartphones) for which it sets up the + hardware buttons appropriately and returns @NULL, so don't forget to test that + the return value is valid before using it. + */ + wxSizer* CreateButtonSizer(long flags); + + /** + Creates a sizer with standard buttons using + CreateButtonSizer() separated from the rest + of the dialog contents by a horizontal wxStaticLine. + + Please notice that just like CreateButtonSizer() this function may return @c + @NULL + if no buttons were created. + */ + wxSizer* CreateSeparatedButtonSizer(long flags); + + /** + Creates a wxStdDialogButtonSizer with standard buttons. @e flags is a bit list + of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, + wxHELP, wxNO_DEFAULT. + + The sizer lays out the buttons in a manner appropriate to the platform. + */ + wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags); + + /** + Performs layout adaptation, usually if the dialog is too large to fit on the + display. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + bool DoLayoutAdapation(); + + /** + This function is called when the titlebar OK button is pressed (PocketPC only). + A command event for the identifier returned by GetAffirmativeId is sent by + default. You can override this function. If the function returns @false, + wxWidgets + will call Close() for the dialog. + */ +#define virtual bool DoOK() /* implementation is private */ + + /** + A static function enabling or disabling layout adaptation for all dialogs. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + static void EnableLayoutAdaptation(bool enable); + + /** + Ends a modal dialog, passing a value to be returned from the ShowModal() + invocation. + + @param retCode + The value that should be returned by ShowModal. + + @sa ShowModal(), GetReturnCode(), SetReturnCode() + */ + void EndModal(int retCode); + + /** + Gets the identifier of the button which works like standard OK button in this + dialog. + + @sa SetAffirmativeId() + */ + int GetAffirmativeId(); + + /** + Override this to return a window containing the main content of the dialog. + This is + particularly useful when the dialog implements pages, such as + wxPropertySheetDialog, + and allows the @ref overview_wxdialogoverview "layout adaptation code" to know + that only the pages need to be made scrollable. + */ + wxWindow* GetContentWindow(); + + /** + Gets the identifier of the button to map presses of @c ESC + button to. + + @sa SetEscapeId() + */ + int GetEscapeId(); + + /** + Returns @true if the dialog has been adapted, usually by making it scrollable + to work with a small display. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + bool GetLayoutAdaptationDone(); + + /** + Gets a value representing the aggressiveness of search for buttons and sizers + to be in the non-scrolling part of a layout-adapted dialog. + Zero switches off adaptation, and 3 allows search for standard buttons anywhere + in the dialog. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + int GetLayoutAdaptationLevel(); + + /** + Gets the adaptation mode, overriding the global adaptation flag. + + See also SetLayoutAdaptationMode() and @ref overview_autoscrollingdialogs + "Automatic scrolling dialogs". + */ + wxDialogLayoutAdaptationMode GetLayoutAdaptationMode(); + + /** + A static function getting the current layout adapter object. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + static wxDialogLayoutAdapter* GetLayoutAdapter(); + + /** + Returns an array of identifiers to be regarded as the main buttons for the + non-scrolling area of a dialog. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + wxArrayInt GetMainButtonIds(); + + /** + Gets the return code for this window. + + @remarks A return code is normally associated with a modal dialog, where + ShowModal() returns a code to the application. + + @sa SetReturnCode(), ShowModal(), EndModal() + */ + int GetReturnCode(); + + /** + 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. + */ + wxToolBar* GetToolBar(); + + /** + Iconizes or restores the dialog. Windows only. + + @param iconize + If @true, iconizes the dialog box; if @false, shows and restores it. + + @remarks Note that in Windows, iconization has no effect since dialog + boxes cannot be iconized. However, applications may + need to explicitly restore dialog boxes under Motif + which have user-iconizable frames, and under Windows + calling Iconize(@false) will bring the window to the + front, as does Show(@true). + */ + void Iconize(bool iconize); + + /** + Returns @true if the dialog box is iconized. Windows only. + + @remarks Always returns @false under Windows since dialogs cannot be + iconized. + */ + bool IsIconized(); + + /** + A static function returning @true if layout adaptation is enabled for all + dialogs. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + static bool IsLayoutAdaptationEnabled(); + + /** + Returns @true if @e id is in the array of identifiers to be regarded as the + main buttons for the non-scrolling area of a dialog. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + bool IsMainButton(wxWindowID& id); + + /** + Returns @true if the dialog box is modal, @false otherwise. + */ + bool IsModal(); + + /** + The default handler for wxEVT_SYS_COLOUR_CHANGED. + + @param event + The colour change event. + + @remarks Changes the dialog's colour to conform to the current settings + (Windows only). Add an event table entry for your + dialog class if you wish the behaviour to be + different (such as keeping a user-defined background + colour). If you do override this function, call + wxEvent::Skip to propagate the notification to child + windows and controls. + + @sa wxSysColourChangedEvent + */ + void OnSysColourChanged(wxSysColourChangedEvent& event); + + /** + Sets the identifier to be used as OK button. When the button with this + identifier is pressed, the dialog calls wxWindow::Validate + and wxWindow::TransferDataFromWindow + and, if they both return @true, closes the dialog with @c wxID_OK return + code. + + Also, when the user presses a hardware OK button on the devices having one or + the special OK button in the PocketPC title bar, an event with this id is + generated. + + By default, the affirmative id is wxID_OK. + + @sa GetAffirmativeId(), SetEscapeId() + */ + void SetAffirmativeId(int id); + + /** + Sets the identifier of the button which should work like the standard + @c CANCEL button in this dialog. When the button with this id is + clicked, the dialog is closed. Also, when the user presses @c ESC + key in the dialog or closes the dialog using the close button in the title bar, + this is mapped to the click of the button with the specified id. + + By default, the escape id is the special value @c wxID_ANY meaning that + @c wxID_CANCEL button is used if it's present in the dialog and + otherwise the button with GetAffirmativeId() + is used. Another special value for @e id is @c wxID_NONE meaning that + @c ESC presses should be ignored. If any other value is given, it + is interpreted as the id of the button to map the escape key to. + */ + void SetEscapeId(int id); + + /** + Sets the icon for this dialog. + + @param icon + The icon to associate with this dialog. + */ + void SetIcon(const wxIcon& icon); + + /** + Sets the icons for this dialog. + + @param icons + The icons to associate with this dialog. + */ + void SetIcons(const wxIconBundle& icons); + + /** + Marks the dialog as having been adapted, usually by making it scrollable to + work with a small display. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + void SetLayoutAdaptationDone(bool done); + + /** + Sets the aggressiveness of search for buttons and sizers to be in the + non-scrolling part of a layout-adapted dialog. + Zero switches off adaptation, and 3 allows search for standard buttons anywhere + in the dialog. + + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + void SetLayoutAdaptationLevel(int level); + + /** + Sets the adaptation mode, overriding the global adaptation flag. @e mode may be + one of the following values: + See also @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" for + more on layout adaptation. + */ + void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode); + + /** + A static function for setting the current layout adapter object, returning the + old adapter. If you call this, you should + delete the old adapter object. + + See also wxDialogLayoutAdapter and @ref overview_autoscrollingdialogs + "Automatic scrolling dialogs". + */ + static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter); + + /** + @b 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 (Show() blocks + control + until the dialog is hidden) or modeless (control returns immediately). + + @param flag + If @true, the dialog will be modal, otherwise it will be modeless. + */ + void SetModal(bool flag); + + /** + Sets the return code for this window. + + @param retCode + The integer return code, usually a control identifier. + + @remarks A return code is normally associated with a modal dialog, where + ShowModal() returns a code to the + application. The function EndModal() calls + SetReturnCode. + + @sa GetReturnCode(), ShowModal(), EndModal() + */ + void SetReturnCode(int retCode); + + /** + Hides or shows the dialog. + + @param show + If @true, the dialog box is shown and brought to the front; + otherwise the box is hidden. If @false and the dialog is + modal, control is returned to the calling program. + + @remarks The preferred way of dismissing a modal dialog is to use + EndModal(). + */ + bool Show(bool show); + + /** + Shows a modal dialog. Program flow does not return until the dialog has been + dismissed with + EndModal(). + + @returns The return value is the value set with SetReturnCode(). + */ + int ShowModal(); +}; + + +/** + @class wxDialogLayoutAdapter + @wxheader{dialog.h} + + This abstract class is the base for classes that help wxWidgets peform run-time + layout adaptation of dialogs. Principally, + this is to cater for small displays by making part of the dialog scroll, but + the application developer may find other + uses for layout adaption. + + By default, there is one instance of wxStandardDialogLayoutAdapter + which can perform adaptation for most custom dialogs and dialogs with book + controls + such as wxPropertySheetDialog. + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_autoscrollingdialogs "Automatic scrolling dialogs" +*/ +class wxDialogLayoutAdapter +{ +public: + /** + Default constructor. + */ + wxDialogLayoutAdapter(); + + /** + Override this to returns @true if adaptation can and should be done. + */ + bool CanDoLayoutAdaptation(wxDialog* dialog); + + /** + Override this to perform layout adaptation, such as making parts of the dialog + scroll and resizing the dialog to fit the display. + Normally this function will be called just before the dialog is shown. + */ + bool DoLayoutAdaptation(wxDialog* dialog); +}; diff --git a/interface/dialup.h b/interface/dialup.h new file mode 100644 index 0000000000..4b53ca0376 --- /dev/null +++ b/interface/dialup.h @@ -0,0 +1,209 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dialup.h +// Purpose: documentation for wxDialUpManager class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDialUpManager + @wxheader{dialup.h} + + This class encapsulates functions dealing with verifying the connection status + of the workstation (connected to the Internet via a direct connection, + connected through a modem or not connected at all) and to establish this + connection if possible/required (i.e. in the case of the modem). + + The program may also wish to be notified about the change in the connection + status (for example, to perform some action when the user connects to the + network the next time or, on the contrary, to stop receiving data from the net + when the user hangs up the modem). For this, you need to use one of the event + macros described below. + + This class is different from other wxWidgets classes in that there is at most + one instance of this class in the program accessed via + wxDialUpManager::Create and you can't + create the objects of this class directly. + + @library{wxcore} + @category{net} + + @seealso + @ref overview_sampledialup "dialup sample", wxDialUpEvent +*/ +class wxDialUpManager +{ +public: + /** + Destructor. + */ + ~wxDialUpManager(); + + /** + Cancel dialing the number initiated with Dial() + with async parameter equal to @true. + + Note that this won't result in DISCONNECTED event being sent. + + @sa IsDialing() + */ + bool CancelDialing(); + + /** + This function should create and return the object of the platform-specific + class derived from wxDialUpManager. You should delete the pointer when you are + done with it. + */ + wxDialUpManager* Create(); + + /** + Dial the given ISP, use @e username and @e password to authenticate. + + The parameters are only used under Windows currently, for Unix you should use + SetConnectCommand() to customize this + functions behaviour. + + If no @e 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 @e async parameter is @false, the function waits until the end of dialing + and returns @true upon successful completion. + + If @e async is @true, the function only initiates the connection and + returns immediately - the result is reported via events (an event is sent + anyhow, but if dialing failed it will be a DISCONNECTED one). + */ + bool Dial(const wxString& nameOfISP = wxEmptyString, + const wxString& username = wxEmptyString, + const wxString& password = wxEmptyString, + bool async = @true); + + /** + Disable automatic check for connection status change - notice that the + @c wxEVT_DIALUP_XXX events won't be sent any more neither. + */ + void DisableAutoCheckOnlineStatus(); + + /** + Enable automatic checks for the connection status and sending of + @c 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. + */ + bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60); + + /** + This function is only implemented under Windows. + + Fills the array with the names of all possible values for the first + parameter to Dial() on this machine and returns + their number (may be 0). + */ + size_t GetISPNames(wxArrayString& names); + + /** + Hang up the currently active dial up connection. + */ + bool HangUp(); + + /** + Returns @true if the computer has a permanent network connection (i.e. is + on a LAN) and so there is no need to use Dial() function to go online. + + @b 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. + */ + bool IsAlwaysOnline(); + + /** + Returns @true if (async) dialing is in progress. + + @sa Dial() + */ + bool IsDialing(); + + /** + 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 + */ +#define bool IsOk() /* implementation is private */ + + /** + 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 + wxDialUpManager::SetWellKnownHost) is reachable. + */ + bool IsOnline(); + + /** + , @b const wxString&@e commandHangup = wxT("/usr/bin/poff")) + + This method is for Unix only. + + Sets the commands to start up the network and to hang up again. + */ + void SetConnectCommand(); + + /** + 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. + + @sa IsOnline() + */ + void SetOnlineStatus(bool isOnline = @true); + + /** + This method is for Unix only. + + Under Unix, the value of well-known host is used to check whether we're + connected to the internet. It is unused under Windows, but this function + is always safe to call. The default value is @c www.yahoo.com:80. + */ + void SetWellKnownHost(const wxString& hostname, int portno = 80); +}; + + +/** + @class wxDialUpEvent + @wxheader{dialup.h} + + This is the event class for the dialup events sent by + wxDialUpManager. + + @library{wxcore} + @category{events} +*/ +class wxDialUpEvent : public wxEvent +{ +public: + /** + Constructor is only used by wxDialUpManager. + */ + wxDialUpEvent(bool isConnected, bool isOwnEvent); + + /** + Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does it + notify about transition from offline to online state or vice versa? + */ + bool IsConnectedEvent(); + + /** + Does this event come from wxDialUpManager::Dial() or from some extrenal + process (i.e. does it result from our own attempt to establish the + connection)? + */ + bool IsOwnEvent(); +}; diff --git a/interface/dir.h b/interface/dir.h new file mode 100644 index 0000000000..5077125fbc --- /dev/null +++ b/interface/dir.h @@ -0,0 +1,268 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dir.h +// Purpose: documentation for wxDirTraverser class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDirTraverser + @wxheader{dir.h} + + wxDirTraverser is an abstract interface which must be implemented by objects + passed to wxDir::Traverse function. + + Example of use (this works almost like wxDir::GetAllFiles): + + @code + class wxDirTraverserSimple : public wxDirTraverser + { + public: + wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } + + virtual wxDirTraverseResult OnFile(const wxString& filename) + { + m_files.Add(filename); + return wxDIR_CONTINUE; + } + + virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) + { + return wxDIR_CONTINUE; + } + + private: + wxArrayString& m_files; + }; + + // get the names of all files in the array + wxArrayString files; + wxDirTraverserSimple traverser(files); + + wxDir dir(dirname); + dir.Traverse(traverser); + @endcode + + @library{wxbase} + @category{file} +*/ +class wxDirTraverser +{ +public: + /** + This function is called for each directory. It may return @c wxSIR_STOP + to abort traversing completely, @c wxDIR_IGNORE to skip this directory but + continue with others or @c wxDIR_CONTINUE to enumerate all files and + subdirectories in this directory. + + This is a pure virtual function and must be implemented in the derived class. + */ + virtual wxDirTraverseResult OnDir(const wxString& dirname); + + /** + This function is called for each file. It may return @c wxDIR_STOP to abort + traversing (for example, if the file being searched is found) or + @c wxDIR_CONTINUE to proceed. + + This is a pure virtual function and must be implemented in the derived class. + */ + virtual wxDirTraverseResult OnFile(const wxString& filename); + + /** + This function is called for each directory which we failed to open for + enumerating. It may return @c wxSIR_STOP to abort traversing completely, + @c wxDIR_IGNORE to skip this directory but continue with others or + @c wxDIR_CONTINUE to retry opening this directory once again. + + The base class version always returns @c wxDIR_IGNORE. + */ + virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); +}; + + +/** + @class wxDir + @wxheader{dir.h} + + wxDir is a portable equivalent of Unix open/read/closedir functions which + allow enumerating of the files in a directory. wxDir allows to enumerate files + as well as directories. + + wxDir also provides a flexible way to enumerate files recursively using + wxDir::Traverse or a simpler + wxDir::GetAllFiles function. + + Example of use: + + @code + wxDir dir(wxGetCwd()); + + if ( !dir.IsOpened() ) + { + // deal with the error here - wxDir would already log an error message + // explaining the exact reason of the failure + return; + } + + puts("Enumerating object files in current directory:"); + + wxString filename; + + bool cont = dir.GetFirst(, filespec, flags); + while ( cont ) + { + printf("%s\n", filename.c_str()); + + cont = dir.GetNext(); + } + @endcode + + @library{wxbase} + @category{file} +*/ +class wxDir +{ +public: + //@{ + /** + Opens the directory for enumeration, use IsOpened() + to test for errors. + */ + wxDir(); + wxDir(const wxString& dir); + //@} + + /** + Destructor cleans up the associated resources. It is not virtual and so this + class is not meant to be used polymorphically. + */ + ~wxDir(); + + /** + Test for existence of a directory with the given name + */ + static bool Exists(const wxString& dir); + + /** + The function returns the path of the first file matching the given @e filespec + or an empty string if there are no files matching it. + + The @e flags parameter may or may not include @c wxDIR_FILES, the + function always behaves as if it were specified. By default, @e flags + includes @c wxDIR_DIRS and so the function recurses into the subdirectories + but if this flag is not specified, the function restricts the search only to + the directory @e dirname itself. + + See also: Traverse() + */ + static wxString FindFirst(const wxString& dirname, + const wxString& filespec, + int flags = wxDIR_DEFAULT); + + /** + The function appends the names of all the files under directory @e dirname + to the array @e files (note that its old content is preserved). Only files + matching the @e filespec are taken, with empty spec matching all the files. + + The @e flags parameter should always include @c wxDIR_FILES or the array + would be unchanged and should include @c wxDIR_DIRS flag to recurse into + subdirectories (both flags are included in the value by default). + + See also: Traverse() + */ + static size_t GetAllFiles(const wxString& dirname, + wxArrayString * files, + const wxString& filespec = wxEmptyString, + int flags = wxDIR_DEFAULT); + + /** + Start enumerating all files matching @e filespec (or all files if it is + empty) and @e flags, return @true on success. + */ + bool GetFirst(wxString* filename, + const wxString& filespec = wxEmptyString, + int flags = wxDIR_DEFAULT); + + /** + Returns the name of the directory itself. The returned string does not have the + trailing path separator (slash or backslash). + */ + wxString GetName(); + + /** + Continue enumerating files which satisfy the criteria specified by the last + call to GetFirst(). + */ + bool GetNext(wxString* filename); + + /** + Returns the size (in bytes) of all files recursively found in @c dir or + @c wxInvalidSize in case of error. + + In case it happens that while traversing folders a file's size can not be read, + that file is added to the @c filesSkipped array, if not @NULL, and then + skipped. + This usually happens with some special folders which are locked by the + operating system + or by another process. Remember that when @c filesSkipped-GetCount() is not + zero, + then the returned value is not 100% accurate and, if the skipped files were + big, it could be + far from real size of the directory. + + See also: wxFileName::GetHumanReadableSize, + wxGetDiskSpace + */ + static wxULongLong GetTotalSize(const wxString& dir, + wxArrayString* filesSkipped = @NULL); + + /** + Returns @true if the directory contains any files matching the given + @e filespec. If @e filespec is empty, look for any files at all. In any + case, even hidden files are taken into account. + */ + bool HasFiles(const wxString& filespec = wxEmptyString); + + /** + Returns @true if the directory contains any subdirectories (if a non + empty @e filespec is given, only check for directories matching it). + The hidden subdirectories are taken into account as well. + */ + bool HasSubDirs(const wxString& dirspec = wxEmptyString); + + /** + Returns @true if the directory was successfully opened by a previous call to + Open(). + */ + bool IsOpened(); + + /** + Open the directory for enumerating, returns @true on success + or @false if an error occurred. + */ + bool Open(const wxString& dir); + + /** + Enumerate all files and directories under the given directory recursively + calling the element of the provided wxDirTraverser + object for each of them. + + More precisely, the function will really recurse into subdirectories if + @e flags contains @c wxDIR_DIRS flag. It will ignore the files (but + still possibly recurse into subdirectories) if @c wxDIR_FILES flag is + given. + + For each found directory, @ref wxDirTraverser::ondir sink.OnDir is called + and @ref wxDirTraverser::onfile sink.OnFile is called for every file. + Depending on the return value, the enumeration may continue or stop. + + The function returns the total number of files found or @c (size_t)-1 on + error. + + See also: GetAllFiles() + */ + size_t Traverse(wxDirTraverser& sink, + const wxString& filespec = wxEmptyString, + int flags = wxDIR_DEFAULT); +}; diff --git a/interface/dirctrl.h b/interface/dirctrl.h new file mode 100644 index 0000000000..dfdcff4b0b --- /dev/null +++ b/interface/dirctrl.h @@ -0,0 +1,184 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dirctrl.h +// Purpose: documentation for wxGenericDirCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGenericDirCtrl + @wxheader{dirctrl.h} + + This control can be used to place a directory listing (with optional files) on + an arbitrary window. + + The control contains a wxTreeCtrl window representing the directory + hierarchy, and optionally, a wxChoice window containing a list of filters. + + @library{wxbase} + @category{ctrl} + @appearance{genericdirctrl.png} +*/ +class wxGenericDirCtrl : public wxControl +{ +public: + //@{ + /** + Main constructor. + + @param parent + Parent window. + + @param id + Window identifier. + + @param dir + Initial folder. + + @param pos + Position. + + @param size + Size. + + @param style + Window style. Please see wxGenericDirCtrl for a list of possible styles. + + @param filter + A filter string, using the same syntax as that for wxFileDialog. This may be + empty if filters + are not being used. + + Example: "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" + + @param defaultFilter + The zero-indexed default filter setting. + + @param name + The window name. + */ + wxGenericDirCtrl(); + wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1, + const wxString& dir = wxDirDialogDefaultFolderStr, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDIRCTRL_3D_INTERNAL|wxBORDER_SUNKEN, + const wxString& filter = wxEmptyString, + int defaultFilter = 0, + const wxString& name = wxTreeCtrlNameStr); + //@} + + /** + Destructor. + */ + ~wxGenericDirCtrl(); + + /** + Collapse the given path. + */ + bool CollapsePath(const wxString& path); + + /** + Collapses the entire tree. + */ + void CollapseTree(); + + /** + Create function for two-step construction. See wxGenericDirCtrl() for details. + */ + bool Create(wxWindow* parent, const wxWindowID id = -1, + const wxString& dir = wxDirDialogDefaultFolderStr, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDIRCTRL_3D_INTERNAL|wxBORDER_SUNKEN, + const wxString& filter = wxEmptyString, + int defaultFilter = 0, + const wxString& name = wxTreeCtrlNameStr); + + /** + Tries to expand as much of the given path as possible, so that the filename or + directory is visible in the tree control. + */ + bool ExpandPath(const wxString& path); + + /** + Gets the default path. + */ + wxString GetDefaultPath(); + + /** + Gets selected filename path only (else empty string). + + This function doesn't count a directory as a selection. + */ + wxString GetFilePath(); + + /** + Returns the filter string. + */ + wxString GetFilter(); + + /** + Returns the current filter index (zero-based). + */ + int GetFilterIndex(); + + /** + Returns a pointer to the filter list control (if present). + */ + wxDirFilterListCtrl* GetFilterListCtrl(); + + /** + Gets the currently-selected directory or filename. + */ + wxString GetPath(); + + /** + Returns the root id for the tree control. + */ + wxTreeItemId GetRootId(); + + /** + Returns a pointer to the tree control. + */ + wxTreeCtrl* GetTreeCtrl(); + + /** + Initializes variables. + */ + void Init(); + + /** + Collapse and expand the tree, thus re-creating it from scratch. + May be used to update the displayed directory content. + */ + void ReCreateTree(); + + /** + Sets the default path. + */ + void SetDefaultPath(const wxString& path); + + /** + Sets the filter string. + */ + void SetFilter(const wxString& filter); + + /** + Sets the current filter index (zero-based). + */ + void SetFilterIndex(int n); + + /** + Sets the current path. + */ + void SetPath(const wxString& path); + + /** + @param show + If @true, hidden folders and files will be displayed by the + control. If @false, they will not be displayed. + */ + void ShowHidden(bool show); +}; diff --git a/interface/dirdlg.h b/interface/dirdlg.h new file mode 100644 index 0000000000..75e2cb902f --- /dev/null +++ b/interface/dirdlg.h @@ -0,0 +1,128 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dirdlg.h +// Purpose: documentation for wxDirDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDirDialog + @wxheader{dirdlg.h} + + This class represents the directory chooser dialog. + + @beginStyleTable + @style{wxDD_DEFAULT_STYLE}: + Equivalent to a combination of wxDEFAULT_DIALOG_STYLE and + wxRESIZE_BORDER (the last one is not used under wxWinCE). + @style{wxDD_DIR_MUST_EXIST}: + The dialog will allow the user to choose only an existing folder. + When this style is not given, a "Create new directory" button is + added to the dialog (on Windows) or some other way is provided to + the user to type the name of a new folder. + @style{wxDD_CHANGE_DIR}: + Change the current working directory to the directory chosen by the + user. + @endStyleTable + + @library{wxcore} + @category{cmndlg} + + @seealso + @ref overview_wxdirdialogoverview "wxDirDialog overview", wxFileDialog +*/ +class wxDirDialog : public wxDialog +{ +public: + /** + Constructor. Use ShowModal() to show + the dialog. + + @param parent + Parent window. + + @param message + Message to show on the dialog. + + @param defaultPath + The default path, or the empty string. + + @param style + The dialog style. See wxDirDialog + + @param pos + Dialog position. Ignored under Windows. + + @param size + Dialog size. Ignored under Windows. + + @param name + The dialog name, not used. + */ + wxDirDialog(wxWindow* parent, + const wxString& message = "Choose a directory", + const wxString& defaultPath = "", + long style = wxDD_DEFAULT_STYLE, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + const wxString& name = "wxDirCtrl"); + + /** + Destructor. + */ + ~wxDirDialog(); + + /** + Returns the message that will be displayed on the dialog. + */ + wxString GetMessage(); + + /** + Returns the default or user-selected path. + */ + wxString GetPath(); + + /** + Sets the message that will be displayed on the dialog. + */ + void SetMessage(const wxString& message); + + /** + Sets the default path. + */ + void SetPath(const wxString& path); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL + otherwise. + */ + int ShowModal(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Pops up a directory selector dialog. The arguments have the same meaning as + those of wxDirDialog::wxDirDialog(). The message is displayed at the top, + and the default_path, if specified, is set as the initial selection. + + The application must check for an empty return value (if the user pressed + Cancel). For example: + @code + const wxString& dir = wxDirSelector("Choose a folder"); + if ( !dir.empty() ) + { + ... + } + @endcode +*/ +wxString wxDirSelector(const wxString& message = wxDirSelectorPromptStr, + const wxString& default_path = "", + long style = 0, + const wxPoint& pos = wxDefaultPosition, + wxWindow * parent = @NULL); + diff --git a/interface/display.h b/interface/display.h new file mode 100644 index 0000000000..5211ecd627 --- /dev/null +++ b/interface/display.h @@ -0,0 +1,126 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: display.h +// Purpose: documentation for wxDisplay class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDisplay + @wxheader{display.h} + + Determines the sizes and locations of displays connected to the system. + + @library{wxcore} + @category{FIXME} + + @seealso + wxClientDisplayRect, wxDisplaySize, wxDisplaySizeMM +*/ +class wxDisplay +{ +public: + /** + Constructor, setting up a wxDisplay instance with the specified display. + + @param index + The index of the display to use. This must be non-negative + and lower than the value returned by GetCount(). + */ + wxDisplay(unsigned index = 0); + + /** + Destructor. + */ + ~wxDisplay(); + + /** + Changes the video mode of this display to the mode specified + in the mode parameter. + + If wxDefaultVideoMode is passed in as the mode parameter, + the defined behaviour is that wxDisplay will reset the video + mode to the default mode used by the display. On Windows, + the behavior is normal. However, there are differences on other + platforms. On Unix variations using X11 extensions it should + behave as defined, but some irregularities may occur. + + On wxMac passing in wxDefaultVideoMode as the mode + parameter does nothing. This happens because carbon + no longer has access to DMUseScreenPrefs, an undocumented + function that changed the video mode to the system + default by using the system's 'scrn' resource. + */ + bool ChangeMode(const wxVideoMode& mode = wxDefaultVideoMode); + + /** + Returns the client area of the display. The client area is the part of the + display available for the normal (non full screen) windows, usually it is the + same as GetGeometry() but it could be less if + there is a taskbar (or equivalent) on this display. + */ + wxRect GetClientArea(); + + /** + Returns the number of connected displays. + */ + static unsigned GetCount(); + + /** + Returns the current video mode that this display is in. + */ + wxVideoMode GetCurrentMode(); + + /** + Returns the bit depth of the display whose index was passed to the constructor. + */ + int GetDepth(); + + /** + Returns the index of the display on which the given point lies. Returns + @c wxNOT_FOUND if the point is not on any connected display. + + @param pt + The point to locate. + */ + static int GetFromPoint(const wxPoint& pt); + + /** + Returns the index of the display on which the given window lies. + + If the window is on more than one display it gets the display that overlaps the + window the most. + + Returns @c wxNOT_FOUND if the window is not on any connected display. + + @param win + The window to locate. + */ + static int GetFromWindow(const wxWindow* win); + + /** + Returns the bounding rectangle of the display whose index was passed to the + constructor. + */ + wxRect GetGeometry(); + + /** + Fills and returns an array with all the video modes that + are supported by this display, or video modes that are + supported by this display and match the mode parameter + (if mode is not wxDefaultVideoMode). + */ + wxArrayVideoModes GetModes(const wxVideoMode& mode = wxDefaultVideoMode); + + /** + Returns the display's name. A name is not available on all platforms. + */ + wxString GetName(); + + /** + Returns @true if the display is the primary display. The primary display is the + one whose index is 0. + */ + bool IsPrimary(); +}; diff --git a/interface/dnd.h b/interface/dnd.h new file mode 100644 index 0000000000..d1e5f7d886 --- /dev/null +++ b/interface/dnd.h @@ -0,0 +1,356 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dnd.h +// Purpose: documentation for wxTextDropTarget class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextDropTarget + @wxheader{dnd.h} + + A predefined drop target for dealing with text data. + + @library{wxcore} + @category{dnd} + + @seealso + @ref overview_wxdndoverview "Drag and drop overview", wxDropSource, + wxDropTarget, wxFileDropTarget +*/ +class wxTextDropTarget : public wxDropTarget +{ +public: + /** + Constructor. + */ + wxTextDropTarget(); + + /** + See wxDropTarget::OnDrop. This function is implemented + appropriately for text, and calls OnDropText(). + */ + virtual bool OnDrop(long x, long y, const void data, size_t size); + + /** + Override this function to receive dropped text. + + @param x + The x coordinate of the mouse. + + @param y + The y coordinate of the mouse. + + @param data + The data being dropped: a wxString. + */ + virtual bool OnDropText(wxCoord x, wxCoord y, + const wxString& data); +}; + + +/** + @class wxDropTarget + @wxheader{dnd.h} + + This class represents a target for a drag and drop operation. A wxDataObject + can be associated with it and by default, this object will be filled with the + data from the + drag source, if the data formats supported by the data object match the drag + source data + format. + + There are various virtual handler functions defined in this class which may be + overridden + to give visual feedback or react in a more fine-tuned way, e.g. by not + accepting data on + the whole window area, but only a small portion of it. The normal sequence of + calls is + wxDropTarget::OnEnter, possibly many times wxDropTarget::OnDragOver, + wxDropTarget::OnDrop and finally wxDropTarget::OnData. + + See @ref overview_wxdndoverview "Drag and drop overview" and @ref + overview_wxdataobjectoverview "wxDataObject overview" + for more information. + + @library{wxcore} + @category{dnd} + + @seealso + wxDropSource, wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject +*/ +class wxDropTarget +{ +public: + /** + Constructor. @e data is the data to be associated with the drop target. + */ + wxDropTarget(wxDataObject* data = @NULL); + + /** + Destructor. Deletes the associated data object, if any. + */ + ~wxDropTarget(); + + /** + This method may only be called from within OnData(). + By default, this method copies the data from the drop source to the + wxDataObject associated with this drop target, + calling its wxDataObject::SetData method. + */ + virtual void GetData(); + + /** + Called after OnDrop() returns @true. By default this + will usually GetData() and will return the suggested + default value @e def. + */ + virtual wxDragResult OnData(wxCoord x, wxCoord y, + wxDragResult def); + + /** + Called when the mouse is being dragged over the drop target. By default, + this calls functions return the suggested return value @e def. + + @param x + The x coordinate of the mouse. + + @param y + The y coordinate of the mouse. + + @param def + Suggested value for return value. Determined by SHIFT or CONTROL key states. + + @returns Returns the desired operation or wxDragNone. This is used for + optical feedback from the side of the drop source, + typically in form of changing the icon. + */ + virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, + wxDragResult def); + + /** + Called when the user drops a data object on the target. Return @false to veto + the operation. + + @param x + The x coordinate of the mouse. + + @param y + The y coordinate of the mouse. + + @returns Return @true to accept the data, @false to veto the operation. + */ + virtual bool OnDrop(wxCoord x, wxCoord y); + + /** + Called when the mouse enters the drop target. By default, this calls + OnDragOver(). + + @param x + The x coordinate of the mouse. + + @param y + The y coordinate of the mouse. + + @param def + Suggested default for return value. Determined by SHIFT or CONTROL key states. + + @returns Returns the desired operation or wxDragNone. This is used for + optical feedback from the side of the drop source, + typically in form of changing the icon. + */ + virtual wxDragResult OnEnter(wxCoord x, wxCoord y, + wxDragResult def); + + /** + Called when the mouse leaves the drop target. + */ + virtual void OnLeave(); + + /** + Sets the data wxDataObject associated with the + drop target and deletes any previously associated data object. + */ + void SetDataObject(wxDataObject* data); +}; + + +/** + @class wxDropSource + @wxheader{dnd.h} + + This class represents a source for a drag and drop operation. + + See @ref overview_wxdndoverview "Drag and drop overview" and @ref + overview_wxdataobjectoverview "wxDataObject overview" + for more information. + + @library{wxcore} + @category{dnd} + + @seealso + wxDropTarget, wxTextDropTarget, wxFileDropTarget +*/ +class wxDropSource +{ +public: + //@{ + /** + The constructors for wxDataObject. + + If you use the constructor without @e data parameter you must call + SetData() later. + + Note that the exact type of @e iconCopy and subsequent parameters differs + between wxMSW and wxGTK: these are cursors under Windows but icons for GTK. + You should use the macro wxDROP_ICON in portable + programs instead of directly using either of these types. + + @param win + The window which initiates the drag and drop operation. + + @param iconCopy + The icon or cursor used for feedback for copy operation. + + @param iconMove + The icon or cursor used for feedback for move operation. + + @param iconNone + The icon or cursor used for feedback when operation can't be done. + */ + wxDropSource(wxWindow* win = @NULL, + const wxIconOrCursor& iconCopy = wxNullIconOrCursor, + const wxIconOrCursor& iconMove = wxNullIconOrCursor, + const wxIconOrCursor& iconNone = wxNullIconOrCursor); + wxDropSource(wxDataObject& data, wxWindow* win = @NULL, + const wxIconOrCursor& iconCopy = wxNullIconOrCursor, + const wxIconOrCursor& iconMove = wxNullIconOrCursor, + const wxIconOrCursor& iconNone = wxNullIconOrCursor); + //@} + + /** + + */ + ~wxDropSource(); + + /** + 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. + + @param flags + If wxDrag_AllowMove is included in the flags, data may + be moved and not only copied (default). If wxDrag_DefaultMove is + specified (which includes the previous flag), this is even the default + operation + + @returns Returns the operation requested by the user, may be wxDragCopy, + wxDragMove, wxDragLink, wxDragCancel or wxDragNone if + an error occurred. + */ + virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly); + + /** + Returns the wxDataObject object that has been assigned previously. + */ + wxDataObject * GetDataObject(); + + /** + 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. + + @param effect + The effect to implement. One of wxDragCopy, wxDragMove, wxDragLink and + wxDragNone. + + @param scrolling + @true if the window is scrolling. MSW only. + + @returns Return @false if you want default feedback, or @true if you + implement your own feedback. The return values is + ignored under GTK. + */ + virtual bool GiveFeedback(wxDragResult effect); + + /** + Set the icon to use for a certain drag result. + + @param res + The drag result to set the icon for. + + @param cursor + The ion to show when this drag result occurs. + */ + void SetCursor(wxDragResult res, const wxCursor& cursor); + + /** + Sets the data wxDataObject associated with the + drop source. This will not delete any previously associated data. + */ + void SetData(wxDataObject& data); +}; + + +/** + @class wxFileDropTarget + @wxheader{dnd.h} + + This is a @ref overview_wxdroptarget "drop target" which accepts files (dragged + from File Manager or Explorer). + + @library{wxcore} + @category{dnd} + + @seealso + @ref overview_wxdndoverview "Drag and drop overview", wxDropSource, + wxDropTarget, wxTextDropTarget +*/ +class wxFileDropTarget : public wxDropTarget +{ +public: + /** + Constructor. + */ + wxFileDropTarget(); + + /** + See wxDropTarget::OnDrop. This function is implemented + appropriately for files, and calls OnDropFiles(). + */ + virtual bool OnDrop(long x, long y, const void data, size_t size); + + /** + Override this function to receive dropped files. + + @param x + The x coordinate of the mouse. + + @param y + The y coordinate of the mouse. + + @param filenames + An array of filenames. + */ + virtual bool OnDropFiles(wxCoord x, wxCoord y, + const wxArrayString& filenames); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + This macro creates either a cursor (MSW) or an icon (elsewhere) with the given + name. Under MSW, the cursor is loaded from the resource file and the icon is + loaded from XPM file under other platforms. + + This macro should be used with + @ref wxDropSource::wxdropsource "wxDropSource constructor". +*/ +#define wxIconOrCursor wxDROP_ICON(const char * name) /* implementation is private */ + diff --git a/interface/docmdi.h b/interface/docmdi.h new file mode 100644 index 0000000000..6858c1f346 --- /dev/null +++ b/interface/docmdi.h @@ -0,0 +1,154 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: docmdi.h +// Purpose: documentation for wxDocMDIParentFrame class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDocMDIParentFrame + @wxheader{docmdi.h} + + The wxDocMDIParentFrame class provides a default top-level frame for + applications using the document/view framework. This class can only be used for + MDI parent frames. + + It cooperates with the wxView, wxDocument, + wxDocManager and wxDocTemplates classes. + + See the example application in @c samples/docview. + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_docviewoverview "Document/view overview", wxMDIParentFrame +*/ +class wxDocMDIParentFrame : public wxMDIParentFrame +{ +public: + //@{ + /** + Constructor. + */ + wxDocMDIParentFrame(); + wxDocMDIParentFrame(wxDocManager* manager, wxFrame * parent, + wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + //@} + + /** + Destructor. + */ + ~wxDocMDIParentFrame(); + + /** + Creates the window. + */ + bool Create(wxDocManager* manager, wxFrame * parent, + wxWindowID id, const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Deletes all views and documents. If no user input cancelled the + operation, the frame will be destroyed and the application will exit. + + Since understanding how document/view clean-up takes place can be difficult, + the implementation of this function is shown below. + */ + void OnCloseWindow(wxCloseEvent& event); +}; + + +/** + @class wxDocMDIChildFrame + @wxheader{docmdi.h} + + The wxDocMDIChildFrame class provides a default frame for displaying documents + on separate windows. This class can only be used for MDI child frames. + + The class is part of the document/view framework supported by wxWidgets, + and cooperates with the wxView, wxDocument, + wxDocManager and wxDocTemplate classes. + + See the example application in @c samples/docview. + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_docviewoverview "Document/view overview", wxMDIChildFrame +*/ +class wxDocMDIChildFrame : public wxMDIChildFrame +{ +public: + /** + Constructor. + */ + wxDocMDIChildFrame(wxDocument* doc, wxView* view, + wxFrame* parent, + wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Destructor. + */ + ~wxDocMDIChildFrame(); + + /** + Returns the document associated with this frame. + */ + wxDocument* GetDocument(); + + /** + Returns the view associated with this frame. + */ + wxView* GetView(); + + /** + Sets the currently active view to be the frame's view. You may need + to override (but still call) this function in order to set the keyboard + focus for your subwindow. + */ + void OnActivate(wxActivateEvent event); + + /** + Closes and deletes the current view and document. + */ + void OnCloseWindow(wxCloseEvent& event); + + /** + Sets the document for this frame. + */ + void SetDocument(wxDocument * doc); + + /** + Sets the view for this frame. + */ + void SetView(wxView * view); + + /** + wxDocument* m_childDocument + + The document associated with the frame. + */ + + + /** + wxView* m_childView + + The view associated with the frame. + */ +}; diff --git a/interface/docview.h b/interface/docview.h new file mode 100644 index 0000000000..cb34867069 --- /dev/null +++ b/interface/docview.h @@ -0,0 +1,1536 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: docview.h +// Purpose: documentation for wxDocTemplate class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDocTemplate + @wxheader{docview.h} + + The wxDocTemplate class is used to model the relationship between a + document class and a view class. + + @library{wxcore} + @category{dvf} + + @seealso + @ref overview_wxdoctemplateoverview "wxDocTemplate overview", wxDocument, wxView +*/ +class wxDocTemplate : public wxObject +{ +public: + /** + Constructor. Create instances dynamically near the start of your application + after creating + a wxDocManager instance, and before doing any document or view operations. + + @e manager is the document manager object which manages this template. + + @e 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. + + @e filter is an appropriate file filter such as @c *.txt. + + @e dir is the default directory to use for file selectors. + + @e ext is the default file extension (such as txt). + + @e 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. + + @e viewTypeName is a name that should be unique for a given view. + + @e 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. + + @e 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. + + @e flags is a bit list of the following: + + wxTEMPLATE_VISIBLE The template may be displayed to the user in dialogs. + wxTEMPLATE_INVISIBLE The template may not be displayed to the user in dialogs. + wxDEFAULT_TEMPLATE_FLAGS Defined as wxTEMPLATE_VISIBLE. + + + + @b Wx::DocTemplate-new( docmgr, descr, filter, dir, + ext, docTypeName, viewTypeName, docClassInfo, viewClassInfo, flags + ) + + + will construct document and view objects from the class information + + @b Wx::DocTemplate-new( docmgr, descr, filter, dir, + ext, docTypeName, viewTypeName, docClassName, viewClassName, flags + ) + + + will construct document and view objects from perl packages + + @b Wx::DocTemplate-new( docmgr, descr, filter, dir, + ext, docTypeName, viewTypeName ) + + + @c Wx::DocTemplate::CreateDocument() and + @c Wx::DocTemplate::CreateView() must be overridden + */ + wxDocTemplate(wxDocManager* manager, const wxString& descr, + const wxString& filter, + const wxString& dir, + const wxString& ext, + const wxString& docTypeName, + const wxString& viewTypeName, + wxClassInfo* docClassInfo = @NULL, + wxClassInfo* viewClassInfo = @NULL, + long flags = wxDEFAULT_TEMPLATE_FLAGS); + + /** + Destructor. + */ + ~wxDocTemplate(); + + /** + Creates a new instance of the associated document class. If you have not + supplied + a wxClassInfo parameter to the template constructor, you will need to override + this + function to return an appropriate document instance. + + This function calls InitDocument() which in turns + calls wxDocument::OnCreate. + */ + wxDocument * CreateDocument(const wxString& path, long flags = 0); + + /** + Creates a new instance of the associated view class. If you have not supplied + a wxClassInfo parameter to the template constructor, you will need to override + this + function to return an appropriate view instance. + */ + wxView * CreateView(wxDocument * doc, long flags = 0); + + /** + Returns the default file extension for the document data, as passed to the + document template constructor. + */ + wxString GetDefaultExtension(); + + /** + Returns the text description of this template, as passed to the document + template constructor. + */ + wxString GetDescription(); + + /** + Returns the default directory, as passed to the document template constructor. + */ + wxString GetDirectory(); + + /** + Returns a pointer to the document manager instance for which this template was + created. + */ + wxDocManager * GetDocumentManager(); + + /** + Returns the document type name, as passed to the document template constructor. + */ + wxString GetDocumentName(); + + /** + Returns the file filter, as passed to the document template constructor. + */ + wxString GetFileFilter(); + + /** + Returns the flags, as passed to the document template constructor. + */ + long GetFlags(); + + /** + Returns the view type name, as passed to the document template constructor. + */ + wxString GetViewName(); + + /** + Initialises the document, calling wxDocument::OnCreate. This is called from + CreateDocument(). + */ + bool InitDocument(wxDocument* doc, const wxString& path, + long flags = 0); + + /** + Returns @true if the document template can be shown in user dialogs, @false + otherwise. + */ + bool IsVisible(); + + /** + Sets the default file extension. + */ + void SetDefaultExtension(const wxString& ext); + + /** + Sets the template description. + */ + void SetDescription(const wxString& descr); + + /** + Sets the default directory. + */ + void SetDirectory(const wxString& dir); + + /** + Sets the pointer to the document manager instance for which this template was + created. + Should not be called by the application. + */ + void SetDocumentManager(wxDocManager * manager); + + /** + Sets the file filter. + */ + void SetFileFilter(const wxString& filter); + + /** + Sets the internal document template flags (see the constructor description for + more details). + */ + void SetFlags(long flags); + + /** + wxString m_defaultExt + + The default extension for files of this type. + */ + + + /** + wxString m_description + + A short description of this template. + */ + + + /** + wxString m_directory + + The default directory for files of this type. + */ + + + /** + wxClassInfo* m_docClassInfo + + Run-time class information that allows document instances to be constructed + dynamically. + */ + + + /** + wxString m_docTypeName + + The named type of the document associated with this template. + */ + + + /** + wxDocTemplate* m_documentManager + + A pointer to the document manager for which this template was created. + */ + + + /** + wxString m_fileFilter + + The file filter (such as @c *.txt) to be used in file selector dialogs. + */ + + + /** + long m_flags + + The flags passed to the constructor. + */ + + + /** + wxClassInfo* m_viewClassInfo + + Run-time class information that allows view instances to be constructed + dynamically. + */ + + + /** + wxString m_viewTypeName + + The named type of the view associated with this template. + */ +}; + + +/** + @class wxDocManager + @wxheader{docview.h} + + The wxDocManager class is part of the document/view framework supported by + wxWidgets, + and cooperates with the wxView, wxDocument + and wxDocTemplate classes. + + @library{wxcore} + @category{dvf} + + @seealso + @ref overview_wxdocmanageroverview "wxDocManager overview", wxDocument, wxView, + wxDocTemplate, wxFileHistory +*/ +class wxDocManager : public wxEvtHandler +{ +public: + /** + Constructor. Create a document manager instance dynamically near the start of + your application + before doing any document or view operations. + + @e flags is currently unused. + + If @e initialize is @true, the Initialize() function will be called + to create a default history list object. If you derive from wxDocManager, you + may wish to call the + base constructor with @false, and then call Initialize in your own constructor, + to allow + your own Initialize or OnCreateFileHistory functions to be called. + */ + wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS, + bool initialize = @true); + + /** + Destructor. + */ + ~wxDocManager(); + + /** + Sets the current view. + */ + void ActivateView(wxView* doc, bool activate = @true); + + /** + Adds the document to the list of documents. + */ + void AddDocument(wxDocument * doc); + + /** + Adds a file to the file history list, if we have a pointer to an appropriate + file menu. + */ + void AddFileToHistory(const wxString& filename); + + /** + Adds the template to the document manager's template list. + */ + void AssociateTemplate(wxDocTemplate * temp); + + /** + Closes all currently opened documents. + */ + bool CloseDocuments(bool force = @true); + + /** + Creates a new document in a manner determined by the @e flags parameter, which + can be: + + wxDOC_NEW Creates a fresh document. + wxDOC_SILENT Silently loads the given document file. + + If wxDOC_NEW is present, a new document will be created and returned, possibly + after + asking the user for a template to use if there is more than one document + template. + If wxDOC_SILENT is present, a new document will be created and the given file + loaded + into it. If neither of these flags is present, the user will be presented with + a file selector for the file to load, and the template to use will be + determined by the + extension (Windows) or by popping up a template choice list (other platforms). + + If the maximum number of documents has been reached, this function + will delete the oldest currently loaded document before creating a new one. + */ + wxDocument* CreateDocument(const wxString& path, long flags); + + /** + Creates a new view for the given document. If more than one view is allowed for + the + document (by virtue of multiple templates mentioning the same document type), a + choice + of view is presented to the user. + */ + wxView* CreateView(wxDocument* doc, long flags); + + /** + Removes the template from the list of templates. + */ + void DisassociateTemplate(wxDocTemplate * temp); + + //@{ + /** + Appends the files in the history list, to the given menu only. + */ + void FileHistoryAddFilesToMenu(); + void FileHistoryAddFilesToMenu(wxMenu* menu); + //@} + + /** + Loads the file history from a config object. + + @sa wxConfig + */ + void FileHistoryLoad(wxConfigBase& config); + + /** + Removes the given menu from the list of menus managed by the file history + object. + */ + void FileHistoryRemoveMenu(wxMenu* menu); + + /** + Saves the file history into a config object. This must be called + explicitly by the application. + + @sa wxConfig + */ + void FileHistorySave(wxConfigBase& resourceFile); + + /** + Use this menu for appending recently-visited document filenames, for convenient + access. Calling this function with a valid menu pointer enables the history + list functionality. + + Note that you can add multiple menus using this function, to be managed by the + file history object. + */ + void FileHistoryUseMenu(wxMenu* menu); + + /** + Given a path, try to find template that matches the extension. This is only + an approximate method of finding a template for creating a document. + */ + wxDocTemplate * FindTemplateForPath(const wxString& path); + + /** + Returns the document associated with the currently active view (if any). + */ + wxDocument * GetCurrentDocument(); + + /** + Returns the currently active view + */ + wxView * GetCurrentView(); + + /** + Returns a reference to the list of documents. + */ + wxList GetDocuments(); + + /** + Returns a pointer to file history. + */ + wxFileHistory * GetFileHistory(); + + /** + Returns the number of files currently stored in the file history. + */ + size_t GetHistoryFilesCount(); + + /** + Returns the directory last selected by the user when opening a file. Initially + empty. + */ + wxString GetLastDirectory(); + + /** + Returns the number of documents that can be open simultaneously. + */ + int GetMaxDocsOpen(); + + /** + Returns a reference to the list of associated templates. + */ + wxList GetTemplates(); + + /** + Initializes data; currently just calls OnCreateFileHistory. Some data cannot + always be initialized in the constructor because the programmer must be given + the opportunity to override functionality. If OnCreateFileHistory was called + from the constructor, an overridden virtual OnCreateFileHistory would not be + called due to C++'s 'interesting' constructor semantics. In fact Initialize + @e is called from the wxDocManager constructor, but this can be + vetoed by passing @false to the second argument, allowing the derived class's + constructor to call Initialize, possibly calling a different OnCreateFileHistory + from the default. + + The bottom line: if you're not deriving from Initialize, forget it and + construct wxDocManager with no arguments. + */ + bool Initialize(); + + /** + Return a string containing a suitable default name for a new document. By + default this is implemented by appending an integer counter to the string + @b unnamed but can be overridden in the derived classes to do something more + appropriate. + */ + wxString MakeNewDocumentName(); + + /** + A hook to allow a derived class to create a different type of file history. + Called + from Initialize(). + */ + wxFileHistory * OnCreateFileHistory(); + + /** + Closes and deletes the currently active document. + */ + void OnFileClose(wxCommandEvent& event); + + /** + Closes and deletes all the currently opened documents. + */ + void OnFileCloseAll(wxCommandEvent& event); + + /** + Creates a document from a list of templates (if more than one template). + */ + void OnFileNew(wxCommandEvent& event); + + /** + Creates a new document and reads in the selected file. + */ + void OnFileOpen(wxCommandEvent& event); + + /** + Reverts the current document by calling wxDocument::Revert for the current + document. + */ + void OnFileRevert(wxCommandEvent& event); + + /** + Saves the current document by calling wxDocument::Save for the current document. + */ + void OnFileSave(wxCommandEvent& event); + + /** + Calls wxDocument::SaveAs for the current document. + */ + void OnFileSaveAs(wxCommandEvent& event); + + /** + Removes the document from the list of documents. + */ + void RemoveDocument(wxDocument * doc); + + /** + Under Windows, pops up a file selector with a list of filters corresponding to + document templates. + The wxDocTemplate corresponding to the selected file's extension is returned. + + On other platforms, if there is more than one document template a choice list + is popped up, + followed by a file selector. + + This function is used in CreateDocument(). + + (doctemplate, path) = My::DocManager-SelectDocumentPath( ... ); + */ + wxDocTemplate * SelectDocumentPath(wxDocTemplate ** templates, + int noTemplates, + wxString& path, + long flags, + bool save); + + /** + Returns a document template by asking the user (if there is more than one + template). + This function is used in CreateDocument(). + + @param templates + Pointer to an array of templates from which to choose a desired template. + + @param noTemplates + Number of templates being pointed to by the templates pointer. + + @param sort + If more than one template is passed in in templates, + then this parameter indicates whether the list of templates that the user + will have to choose from is sorted or not when shown the choice box dialog. + Default is @false. + */ + wxDocTemplate * SelectDocumentType(wxDocTemplate ** templates, + int noTemplates, + bool sort=@false); + + /** + Returns a document template by asking the user (if there is more than one + template), + displaying a list of valid views. This function is used in CreateView(). + The dialog normally will not appear because the array of templates only contains + those relevant to the document in question, and often there will only be one + such. + + @param templates + Pointer to an array of templates from which to choose a desired template. + + @param noTemplates + Number of templates being pointed to by the templates pointer. + + @param sort + If more than one template is passed in in templates, + then this parameter indicates whether the list of templates that the user + will have to choose from is sorted or not when shown the choice box dialog. + Default is @false. + */ + wxDocTemplate * SelectViewType(wxDocTemplate ** templates, + int noTemplates, + bool sort=@false); + + /** + Sets the directory to be displayed to the user when opening a file. Initially + this is empty. + */ + void SetLastDirectory(const wxString& dir); + + /** + Sets the maximum number of documents that can be open at a time. By default, + this + is 10,000. If you set it to 1, existing documents will be saved and deleted + when the user tries to open or create a new one (similar to the behaviour + of Windows Write, for example). Allowing multiple documents gives behaviour + more akin to MS Word and other Multiple Document Interface applications. + */ + void SetMaxDocsOpen(int n); + + /** + wxView* m_currentView + + The currently active view. + */ + + + /** + int m_defaultDocumentNameCounter + + Stores the integer to be used for the next default document name. + */ + + + /** + wxList m_docs + + A list of all documents. + */ + + + /** + wxFileHistory* m_fileHistory + + A pointer to an instance of wxFileHistory, + which manages the history of recently-visited files on the File menu. + */ + + + /** + long m_flags + + Stores the flags passed to the constructor. + */ + + + /** + The directory last selected by the user when opening a file. + + wxFileHistory* m_fileHistory + */ + + + /** + int m_maxDocsOpen + + Stores the maximum number of documents that can be opened before + existing documents are closed. By default, this is 10,000. + */ +}; + + +/** + @class wxView + @wxheader{docview.h} + + The view class can be used to model the viewing and editing component of + an application's file-based data. It is part of the document/view framework + supported by wxWidgets, + and cooperates with the wxDocument, wxDocTemplate + and wxDocManager classes. + + @library{wxcore} + @category{dvf} + + @seealso + @ref overview_wxviewoverview "wxView overview", wxDocument, wxDocTemplate, + wxDocManager +*/ +class wxView : public wxEvtHandler +{ +public: + /** + Constructor. Define your own default constructor to initialize + application-specific + data. + */ + wxView(); + + /** + Destructor. Removes itself from the document's list of views. + */ + ~wxView(); + + /** + Call this from your view frame's OnActivate member to tell the framework which + view is + currently active. If your windowing system doesn't call OnActivate, you may + need to + call this function from any place where you know the view must + be active, and the framework will need to get the current view. + + The prepackaged view frame wxDocChildFrame calls Activate() from its OnActivate + member. + + This function calls OnActivateView(). + */ + virtual void Activate(bool activate); + + /** + Closes the view by calling OnClose. If @e deleteWindow is @true, this function + should + delete the window associated with the view. + */ + virtual bool Close(bool deleteWindow = @true); + + /** + Gets a pointer to the document associated with the view. + */ + wxDocument* GetDocument(); + + /** + Returns a pointer to the document manager instance associated with this view. + */ + wxDocManager* GetDocumentManager(); + + /** + Gets the frame associated with the view (if any). Note that this "frame'' is + not a wxFrame at all in the generic MDI implementation which uses the notebook + pages instead of the frames and this is why this method returns a wxWindow and + not a wxFrame. + */ + wxWindow * GetFrame(); + + /** + Gets the name associated with the view (passed to the wxDocTemplate + constructor). + Not currently used by the framework. + */ + wxString GetViewName(); + + /** + Called when a view is activated by means of Activate(). The default + implementation does + nothing. + */ + virtual void OnActivateView(bool activate, wxView * activeView, + wxView * deactiveView); + + /** + Called when the filename has changed. The default implementation constructs a + suitable title and sets the title of the view frame (if any). + */ + virtual void OnChangeFilename(); + + /** + Implements closing behaviour. The default implementation calls wxDocument::Close + to close the associated document. Does not delete the view. The application + may wish to do some cleaning up operations in this function, @e if a + call to wxDocument::Close succeeded. For example, if your views + all share the same window, you need to disassociate the window from the view + and perhaps clear the window. If @e deleteWindow is @true, delete the + frame associated with the view. + */ + virtual bool OnClose(bool deleteWindow); + + /** + Override this to clean up the view when the document is being + closed. + */ + virtual void OnClosingDocument(); + + /** + wxDocManager or wxDocument creates a wxView via a wxDocTemplate. + Just after the wxDocTemplate creates the wxView, it calls + OnCreate(). In its OnCreate member function, the wxView can create a + wxDocChildFrame + or a derived class. This wxDocChildFrame provides user interface + elements to view and/or edit the contents of the wxDocument. + + By default, simply returns @true. If the function returns @false, the + view will be deleted. + */ + virtual bool OnCreate(wxDocument* doc, long flags); + + /** + If the printing framework is enabled in the library, this function returns a + wxPrintout object for the purposes of printing. It should create a new object + every time it is called; the framework will delete objects it creates. + + By default, this function returns an instance of wxDocPrintout, which prints + and previews one page by calling OnDraw(). + + Override to return an instance of a class other than wxDocPrintout. + */ + virtual wxPrintout* OnCreatePrintout(); + + /** + Override this function to render the view on the given device context. + */ + virtual void OnDraw(wxDC* dc); + + /** + Called when the view should be updated. @e sender is a pointer to the view + that sent the update request, or @NULL if no single view requested the update + (for instance, + when the document is opened). @e hint is as yet unused but may in future contain + application-specific information for making updating more efficient. + */ + virtual void OnUpdate(wxView* sender, wxObject* hint); + + /** + Associates the given document with the view. Normally called by the + framework. + */ + void SetDocument(wxDocument* doc); + + /** + Sets the frame associated with this view. The application should call this + if possible, to tell the view about the frame. + + See GetFrame() for the explanation about the mismatch + between the "Frame'' in the method name and the type of its parameter. + */ + void SetFrame(wxWindow* frame); + + /** + Sets the view type name. Should only be called by the framework. + */ + void SetViewName(const wxString& name); + + /** + wxDocument* m_viewDocument + + The document associated with this view. There may be more than one view per + document, but there can never be more than one document for one view. + */ + + + /** + wxFrame* m_viewFrame + + Frame associated with the view, if any. + */ + + + /** + wxString m_viewTypeName + + The view type name given to the wxDocTemplate constructor, copied to this + variable when the view is created. Not currently used by the framework. + */ +}; + + +/** + @class wxDocChildFrame + @wxheader{docview.h} + + The wxDocChildFrame class provides a default frame for displaying documents + on separate windows. This class can only be used for SDI (not MDI) child frames. + + The class is part of the document/view framework supported by wxWidgets, + and cooperates with the wxView, wxDocument, + wxDocManager and wxDocTemplate classes. + + See the example application in @c samples/docview. + + @library{wxcore} + @category{dvf} + + @seealso + @ref overview_docviewoverview "Document/view overview", wxFrame +*/ +class wxDocChildFrame : public wxFrame +{ +public: + /** + Constructor. + */ + wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent, + wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Destructor. + */ + ~wxDocChildFrame(); + + /** + Returns the document associated with this frame. + */ + wxDocument* GetDocument(); + + /** + Returns the view associated with this frame. + */ + wxView* GetView(); + + /** + Sets the currently active view to be the frame's view. You may need + to override (but still call) this function in order to set the keyboard + focus for your subwindow. + */ + void OnActivate(wxActivateEvent event); + + /** + Closes and deletes the current view and document. + */ + void OnCloseWindow(wxCloseEvent& event); + + /** + Sets the document for this frame. + */ + void SetDocument(wxDocument * doc); + + /** + Sets the view for this frame. + */ + void SetView(wxView * view); + + /** + wxDocument* m_childDocument + + The document associated with the frame. + */ + + + /** + wxView* m_childView + + The view associated with the frame. + */ +}; + + +/** + @class wxDocParentFrame + @wxheader{docview.h} + + The wxDocParentFrame class provides a default top-level frame for + applications using the document/view framework. This class can only be used for + SDI (not MDI) parent frames. + + It cooperates with the wxView, wxDocument, + wxDocManager and wxDocTemplates classes. + + See the example application in @c samples/docview. + + @library{wxcore} + @category{dvf} + + @seealso + @ref overview_docviewoverview "Document/view overview", wxFrame +*/ +class wxDocParentFrame : public wxFrame +{ +public: + //@{ + /** + Constructor. + */ + wxDocParentFrame(); + wxDocParentFrame(wxDocManager* manager, wxFrame * parent, + wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + //@} + + /** + Destructor. + */ + ~wxDocParentFrame(); + + /** + Used in two-step construction. + */ + bool Create(wxDocManager* manager, wxFrame * parent, + wxWindowID id, const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Returns the associated @ref overview_wxdocmanager "document manager object". + */ + wxDocManager * GetDocumentManager(); + + /** + 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 OnCloseWindow(wxCloseEvent& event); +}; + + +/** + @class wxDocument + @wxheader{docview.h} + + The document class can be used to model an application's file-based + data. It is part of the document/view framework supported by wxWidgets, + and cooperates with the wxView, wxDocTemplate + and wxDocManager classes. + + @library{wxcore} + @category{dvf} + + @seealso + @ref overview_wxdocumentoverview "wxDocument overview", wxView, wxDocTemplate, + wxDocManager +*/ +class wxDocument : public wxEvtHandler +{ +public: + /** + Constructor. Define your own default constructor to initialize + application-specific + data. + */ + wxDocument(); + + /** + Destructor. Removes itself from the document manager. + */ + ~wxDocument(); + + /** + If the view is not already in the list of views, adds the view and calls + OnChangedViewList. + */ + virtual bool AddView(wxView * view); + + /** + Closes the document, by calling OnSaveModified and then (if this returned @true) + OnCloseDocument. + This does not normally delete the document object: use DeleteAllViews to do + this implicitly. + */ + virtual bool Close(); + + /** + Calls wxView::Close and deletes each view. Deleting the final view will + implicitly + delete the document itself, because the wxView destructor calls RemoveView. This + in turns calls OnChangedViewList(), whose default implemention is to + save and delete the document if no views exist. + */ + virtual bool DeleteAllViews(); + + /** + Returns a pointer to the command processor associated with this document. + + See wxCommandProcessor. + */ + wxCommandProcessor* GetCommandProcessor(); + + /** + Gets a pointer to the associated document manager. + */ + wxDocManager* GetDocumentManager(); + + /** + Gets the document type name for this document. See the comment for + documentTypeName. + */ + wxString GetDocumentName(); + + /** + Gets a pointer to the template that created the document. + */ + wxDocTemplate* GetDocumentTemplate(); + + /** + Intended to return a suitable window for using as a parent for document-related + dialog boxes. By default, uses the frame associated with the first view. + */ + wxWindow* GetDocumentWindow(); + + /** + Gets the filename associated with this document, or "" if none is + associated. + */ + wxString GetFilename(); + + /** + 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() + */ + wxView * GetFirstView(); + + /** + Gets the title for this document. The document title is used for an associated + frame (if any), and is usually constructed by the framework from + the filename. + */ + wxString GetTitle(); + + /** + Return the document name suitable to be shown to the user. The default + implementation uses the document title, if any, of the name part of the + document filename if it was set or, otherwise, the string @b unnamed. + */ + virtual wxString GetUserReadableName(); + + /** + Returns the list whose elements are the views on the document. + + See also: GetFirstView() + */ + wxList GetViews(); + + /** + 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(). + */ + virtual bool IsModified(); + + //@{ + /** + 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. + */ + virtual istream LoadObject(istream& stream); + virtual wxInputStream LoadObject(wxInputStream& stream); + //@} + + /** + Call with @true to mark the document as modified since the last save, @false + otherwise. + You may need to override this if your document view maintains its own + record of being modified (for example if using wxTextWindow to view and edit + the document). + + See also IsModified(). + */ + virtual void Modify(bool modify); + + /** + Called when a view is added to or deleted from this document. The default + implementation saves and deletes the document if no views exist (the last + one has just been removed). + */ + virtual void OnChangedViewList(); + + /** + The default implementation calls DeleteContents (an empty implementation) + sets the modified flag to @false. Override this to + supply additional behaviour when the document is closed with Close. + */ + virtual bool OnCloseDocument(); + + /** + Called just after the document object is created to give it a chance + to initialize itself. The default implementation uses the + template associated with the document to create an initial view. + If this function returns @false, the document is deleted. + */ + virtual bool OnCreate(const wxString& path, long flags); + + /** + Override this function if you want a different (or no) command processor + to be created when the document is created. By default, it returns + an instance of wxCommandProcessor. + + See wxCommandProcessor. + */ + virtual wxCommandProcessor* OnCreateCommandProcessor(); + + /** + The default implementation calls OnSaveModified and DeleteContents, makes a + default title for the + document, and notifies the views that the filename (in fact, the title) has + changed. + */ + virtual bool OnNewDocument(); + + /** + Constructs an input file stream for the given filename (which must not be + empty), + and calls LoadObject. If LoadObject returns @true, the document is set to + unmodified; otherwise, an error message box is displayed. The document's + views are notified that the filename has changed, to give windows an opportunity + to update their titles. All of the document's views are then updated. + */ + virtual bool OnOpenDocument(const wxString& filename); + + /** + Constructs an output file stream for the given filename (which must not be + empty), + and calls SaveObject. If SaveObject returns @true, the document is set to + unmodified; otherwise, an error message box is displayed. + */ + virtual bool OnSaveDocument(const wxString& filename); + + /** + If the document has been modified, prompts the user to ask if the changes should + be changed. If the user replies Yes, the Save function is called. If No, the + document is marked as unmodified and the function succeeds. If Cancel, the + function fails. + */ + virtual bool OnSaveModified(); + + /** + Removes the view from the document's list of views, and calls OnChangedViewList. + */ + virtual bool RemoveView(wxView* view); + + /** + Saves the document by calling OnSaveDocument if there is an associated filename, + or SaveAs if there is no filename. + */ + virtual bool Save(); + + /** + Prompts the user for a file to save to, and then calls OnSaveDocument. + */ + virtual bool SaveAs(); + + //@{ + /** + Override this function and call it from your own SaveObject before + streaming your own data. SaveObject is called by the framework + automatically when the document contents need to be saved. + + Note that only one of these forms exists, depending on how wxWidgets + was configured. + */ + virtual ostream SaveObject(ostream& stream); + virtual wxOutputStream SaveObject(wxOutputStream& stream); + //@} + + /** + Sets the command processor to be used for this document. The document will then + be responsible + for its deletion. Normally you should not call this; override + OnCreateCommandProcessor + instead. + + See wxCommandProcessor. + */ + virtual void SetCommandProcessor(wxCommandProcessor * processor); + + /** + Sets the document type name for this document. See the comment for + documentTypeName. + */ + void SetDocumentName(const wxString& name); + + /** + Sets the pointer to the template that created the document. Should only be + called by the + framework. + */ + void SetDocumentTemplate(wxDocTemplate* templ); + + /** + Sets the filename for this document. Usually called by the framework. + + If @e notifyViews is @true, wxView::OnChangeFilename is called for all views. + */ + void SetFilename(const wxString& filename, + bool notifyViews = @false); + + /** + Sets the title for this document. The document title is used for an associated + frame (if any), and is usually constructed by the framework from + the filename. + */ + void SetTitle(const wxString& title); + + /** + Updates all views. If @e sender is non-@NULL, does not update this view. + + @e hint represents optional information to allow a view to optimize its update. + */ + void UpdateAllViews(wxView* sender = @NULL, wxObject* hint = @NULL); + + /** + wxCommandProcessor* m_commandProcessor + + A pointer to the command processor associated with this document. + */ + + + /** + wxString m_documentFile + + Filename associated with this document ("" if none). + */ + + + /** + bool m_documentModified + + @true if the document has been modified, @false otherwise. + */ + + + /** + wxDocTemplate * m_documentTemplate + + A pointer to the template from which this document was created. + */ + + + /** + wxString m_documentTitle + + Document title. The document title is used for an associated + frame (if any), and is usually constructed by the framework from + the filename. + */ + + + /** + wxString m_documentTypeName + + The document type name given to the wxDocTemplate constructor, copied to this + variable when the document is created. If several document templates are + created that use the same document type, this variable is used in + wxDocManager::CreateView + to collate a list of alternative view types that can be used on this kind of + document. Do not change the value of this variable. + */ + + + /** + wxList m_documentViews + + List of wxView instances associated with this document. + */ +}; + + +/** + @class wxFileHistory + @wxheader{docview.h} + + The wxFileHistory encapsulates a user interface convenience, the + list of most recently visited files as shown on a menu (usually the File menu). + + wxFileHistory can manage one or more file menus. More than one menu may be + required + in an MDI application, where the file history should appear on each MDI child + menu + as well as the MDI parent frame. + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_wxfilehistoryoverview "wxFileHistory overview", wxDocManager +*/ +class wxFileHistory : public wxObject +{ +public: + /** + Constructor. Pass the maximum number of files that should be stored and + displayed. + + @e 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. + */ + wxFileHistory(size_t maxFiles = 9, + wxWindowID idBase = wxID_FILE1); + + /** + Destructor. + */ + ~wxFileHistory(); + + /** + Adds a file to the file history list, if the object has a pointer to an + appropriate file menu. + */ + void AddFileToHistory(const wxString& filename); + + //@{ + /** + Appends the files in the history list, to the given menu only. + */ + void AddFilesToMenu(); + void AddFilesToMenu(wxMenu* menu); + //@} + + /** + Returns the base identifier for the range used for appending items. + */ + wxWindowID GetBaseId(); + + /** + Returns the number of files currently stored in the file history. + */ + size_t GetCount(); + + /** + Returns the file at this index (zero-based). + */ + wxString GetHistoryFile(size_t index); + + /** + Returns the maximum number of files that can be stored. + */ + int GetMaxFiles(); + + /** + Returns the list of menus that are managed by this file history object. + + @sa UseMenu() + */ + const wxList GetMenus(); + + /** + Loads the file history from the given config object. This function should be + called explicitly by the application. + + @sa wxConfig + */ + void Load(wxConfigBase& config); + + /** + Removes the specified file from the history. + */ + void RemoveFileFromHistory(size_t i); + + /** + Removes this menu from the list of those managed by this object. + */ + void RemoveMenu(wxMenu* menu); + + /** + Saves the file history into the given config object. This must be called + explicitly by the application. + + @sa wxConfig + */ + void Save(wxConfigBase& config); + + /** + Sets the base identifier for the range used for appending items. + */ + void SetBaseId(wxWindowID baseId); + + /** + Adds this menu to the list of those menus that are managed by this file history + object. + Also see AddFilesToMenu() for + initializing the menu with filenames that are already in the history when this + function is called, as this is not done automatically. + */ + void UseMenu(wxMenu* menu); + + /** + char** m_fileHistory + + A character array of strings corresponding to the most recently opened + files. + */ + + + /** + size_t m_fileHistoryN + + The number of files stored in the history array. + */ + + + /** + size_t m_fileMaxFiles + + The maximum number of files to be stored and displayed on the menu. + */ + + + /** + wxMenu* m_fileMenu + + The file menu used to display the file history list (if enabled). + */ +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Copies the given file to @e stream. Useful when converting an old application to + use streams (within the document/view framework, for example). +*/ +bool wxTransferFileToStream(const wxString& filename, + ostream& stream); + diff --git a/interface/dragimag.h b/interface/dragimag.h new file mode 100644 index 0000000000..63f390f55b --- /dev/null +++ b/interface/dragimag.h @@ -0,0 +1,218 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dragimag.h +// Purpose: documentation for wxDragImage class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDragImage + @wxheader{dragimag.h} + + This class is used when you wish to drag an object on the screen, + and a simple cursor is not enough. + + On Windows, the Win32 API is used to achieve smooth dragging. On other + platforms, + wxGenericDragImage is used. Applications may also prefer to use + wxGenericDragImage on Windows, too. + + @b wxPython note: wxPython uses wxGenericDragImage on all platforms, but + uses the wxDragImage name. + + 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 @c samples/dragimag for an example. + + @library{wxcore} + @category{FIXME} +*/ +class wxDragImage : public wxObject +{ +public: + //@{ + /** + ) + + Constructs a drag image an optional cursor. This constructor is only available + for + wxGenericDragImage, and can be used when the application + supplies DoDrawImage() and GetImageRect(). + + @param image + Icon or bitmap to be used as the drag image. The bitmap can + have a mask. + + @param text + Text used to construct a drag image. + + @param cursor + Optional cursor to combine with the image. + + @param hotspot + This parameter is deprecated. + + @param treeCtrl + Tree control for constructing a tree drag image. + + @param listCtrl + List control for constructing a list drag image. + + @param id + Tree or list control item id. + */ + wxDragImage(); + wxDragImage(const wxBitmap& image, + const wxCursor& cursor = wxNullCursor); + wxDragImage(const wxIcon& image, + const wxCursor& cursor = wxNullCursor); + wxDragImage(const wxString& text, + const wxCursor& cursor = wxNullCursor); + wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id); + wxDragImage(const wxListCtrl& treeCtrl, long id); + wxDragImage(const wxCursor& cursor = wxNullCursor); + //@} + + //@{ + /** + Start dragging the image, using the first window to capture the mouse and the + second + to specify the bounding area. This form is equivalent to using the first form, + but more convenient than working out the bounding rectangle explicitly. + + You need to then call Show() + and Move() to show the image on the screen. + + Call EndDrag() when the drag has finished. + + Note that this call automatically calls CaptureMouse. + + @param hotspot + The location of the drag position relative to the upper-left corner + of the image. + + @param window + The window that captures the mouse, and within which the dragging + is limited unless fullScreen is @true. + + @param boundingWindow + In the second form of the function, specifies the + area within which the drag occurs. + + @param fullScreen + If @true, specifies that the drag will be visible over the full + screen, or over as much of the screen as is specified by rect. Note that the + mouse will + still be captured in window. + + @param rect + If non-@NULL, specifies the rectangle (in screen coordinates) that + bounds the dragging operation. Specifying this can make the operation more + efficient + by cutting down on the area under consideration, and it can also make a visual + difference + since the drag is clipped to this area. + */ + bool BeginDrag(const wxPoint& hotspot, wxWindow* window, + bool fullScreen = @false, + wxRect* rect = @NULL); + bool BeginDrag(const wxPoint& hotspot, wxWindow* window, + wxWindow* boundingWindow); + //@} + + /** + Draws the image on the device context with top-left corner at the given + position. + + This function is only available with wxGenericDragImage, to allow applications + to + draw their own image instead of using an actual bitmap. If you override this + function, + you must also override GetImageRect(). + */ + virtual bool DoDrawImage(wxDC& dc, const wxPoint& pos); + + /** + Call this when the drag has finished. + + Note that this call automatically calls ReleaseMouse. + */ + bool EndDrag(); + + /** + Returns the rectangle enclosing the image, assuming that the image is drawn + with its + top-left corner at the given point. + + This function is available in wxGenericDragImage only, and may be overridden + (together with + wxDragImage::DoDrawImage) to provide a virtual drawing capability. + */ + virtual wxRect GetImageRect(const wxPoint& pos); + + /** + Hides the image. You may wish to call this before updating the window + contents (perhaps highlighting an item). Then call Move() + and Show(). + */ + bool Hide(); + + /** + Call this to move the image to a new position. The image will only be shown if + Show() has been called previously (for example + at the start of the drag). + + @e 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. + */ + bool Move(const wxPoint& pt); + + /** + Shows the image. Call this at least once when dragging. + */ + bool Show(); + + /** + Override this if you wish to draw the window contents to the backing bitmap + yourself. This can be desirable if you wish to avoid flicker by not having to + redraw the updated window itself just before dragging, which can cause a + flicker just + as the drag starts. Instead, paint the drag image's backing bitmap to show the + appropriate + graphic @e minus the objects to be dragged, and leave the window itself to be + updated + by the drag image. This can provide eerily smooth, flicker-free drag behaviour. + + The default implementation copies the window contents to the backing bitmap. A + new + implementation will normally copy information from another source, such as from + its + own backing bitmap if it has one, or directly from internal data structures. + + This function is available in wxGenericDragImage only. + */ + bool UpdateBackingFromWindow(wxDC& windowDC, wxMemoryDC& destDC, + const wxRect& sourceRect, + const wxRect& destRect); +}; diff --git a/interface/dynarray.h b/interface/dynarray.h new file mode 100644 index 0000000000..8d0464c58b --- /dev/null +++ b/interface/dynarray.h @@ -0,0 +1,658 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dynarray.h +// Purpose: documentation for wxArray class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxArrayT + @wxheader{dynarray.h} + + This section describes the so called @e dynamic arrays. This is a C + array-like type safe data structure i.e. the member access time is constant + (and not + linear according to the number of container elements as for linked lists). + However, these + arrays are dynamic in the sense that they will automatically allocate more + memory if there is not enough of it for adding a new element. They also perform + range checking on the index values but in debug mode only, so please be sure to + compile your application in debug mode to use it (see @ref + overview_debuggingoverview "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 @ref + wxArray::memorymanagement "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 @e any space at all. + + wxWidgets has three different kinds of array. All of them derive from + wxBaseArray class which works with untyped data and can not be used directly. + The standard macros WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() and + WX_DEFINE_OBJARRAY() are used to define a new class deriving from it. The + classes declared will be called in this documentation wxArray, wxSortedArray and + wxObjArray but you should keep in mind that no classes with such names actually + exist, each time you use one of 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 @b not work, + please use wxObjArray for storing floats and doubles. + + wxSortedArray is a wxArray variant which should be used when searching in the + array is a frequently used operation. It requires you to define an additional + function for comparing two elements of the array element type and always stores + its items in the sorted order (according to this function). Thus, it is + wxArray::Index function execution time is O(log(N)) instead of + O(N) for the usual arrays but the wxArray::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: + + @code + #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! + @endcode + + It is not as elegant as writing + + @code + typedef std::vectorMyDirectory ArrayOfDirectories; + @endcode + + but is not that complicated and allows the code to be compiled with any, however + dumb, C++ compiler in the world. + + Remember to include wx/arrimpl.cpp just before each WX_DEFINE_OBJARRAY + ocurrence in your code, even if you have several in the same file. + + Things are much simpler for wxArray and wxSortedArray however: it is enough + just to write + + @code + WX_DEFINE_ARRAY_INT(int, ArrayOfInts); + WX_DEFINE_SORTED_ARRAY_INT(int, ArrayOfSortedInts); + @endcode + + i.e. there is only one @c DEFINE macro and no need for separate + @c DECLARE one. For the arrays of the primitive types, the macros + @c WX_DEFINE_ARRAY_CHAR/SHORT/INT/SIZE_T/LONG/DOUBLE should be used + depending on the sizeof of the values (notice that storing values of smaller + type, e.g. shorts, in an array of larger one, e.g. @c ARRAY_INT, does + not work on all architectures!). + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxcontaineroverview "Container classes overview", wxListT, + wxVectorT +*/ +class wxArray +{ +public: + //@{ + /** + Appends the given number of @e copies of the @e item to the array + consisting of the elements of type @e T. + + The first version is used with wxArray. The second is used with wxSortedArray, + returning the index where @e item is stored. The third and the + fourth ones 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 + @e copies parameter and modify the elements in place later if you plan to + append a lot of items. + */ + void Add(T item, size_t copies = 1); + size_t Add(T item); + void Add(T * item); + void Add(T & item, size_t copies = 1); + //@} + + /** + Inserts the given @e item into the array in the specified @e index + position. + + Be aware that you will set out the order of the array if you give a wrong + position. + + This function is useful in conjunction with + wxArray::IndexForInsert for a common operation + of "insert only if not found". + */ + void AddAt(T item, size_t index); + + /** + wxArray::Add + + wxArray::AddAt + + wxArray::Insert + + wxArray::SetCount + + WX_APPEND_ARRAY + + WX_PREPEND_ARRAY + */ + + + /** + Preallocates memory for a given number of array elements. It is worth calling + when the number of items which are going to be added to the array is known in + advance because it will save unneeded memory reallocation. If the array already + has enough memory for the given number of items, nothing happens. In any case, + the existing contents of the array is not modified. + */ + void Alloc(size_t count); + + /** + This function does the same as wxArray::Empty and additionally + frees the memory allocated to the array. + */ + void Clear(); + + /** + Array classes are 100% C++ objects and as such they have the appropriate copy + constructors and assignment operators. Copying wxArray just copies the elements + but copying wxObjArray copies the arrays items. However, for memory-efficiency + sake, neither of these classes has virtual destructor. It is not very important + for wxArray which has trivial destructor anyhow, but it does mean that you + should avoid deleting wxObjArray through a wxBaseArray pointer (as you would + never use wxBaseArray anyhow it shouldn't be a problem) and that you should not + derive your own classes from the array classes. + + @ref wxArray::ctordef "wxArray default constructor" + + @ref wxArray::ctorcopy "wxArray copy constructors and assignment operators" + + @ref wxArray::dtor ~wxArray + */ + + + //@{ + /** + (T first, T second)@e compareFunction) + + 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 @e T where @e 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. + */ + wxArray(); + wxObjArray(); + wxSortedArray(); + //@} + + /** + Removes the element from the array, but, unlike, + wxArray::Remove doesn't delete it. The function returns the + pointer to the removed element. + */ + T * Detach(size_t index); + + /** + Empties the array. For wxObjArray classes, this destroys all of the array + elements. For wxArray and wxSortedArray this does nothing except marking the + array of being empty - this function does not free the allocated memory, use + wxArray::Clear for this. + */ + void Empty(); + + /** + Return the number of items in the array. + */ + size_t GetCount(); + + //@{ + /** + 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 @e searchFromEnd parameter. @c 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). + + @b NB: even for wxObjArray classes, the operator==() of the elements in the + array is @b not used by this function. It searches exactly the given + element in the array and so will only succeed if this element had been + previously added to the array, but fail even if another, identical, element is + in the array. + */ + int Index(T& item, bool searchFromEnd = @false); + int Index(T& item); + //@} + + /** + Search for a place to insert @e item into the sorted array (binary search). + The index returned is just before the first existing item that is greater or + equal + (according to the compare function) to the given @e item. + + You have to do extra work to know if the @e item already exists in array. + + This function is useful in conjunction with + wxArray::AddAt for a common operation + of "insert only if not found". + */ + size_t IndexForInsert(T item); + + //@{ + /** + Insert the given number of @e copies of the @e item into the array before + the existing item @e n - thus, @e Insert(something, 0u) will insert an + item in such way that it will become the first array element. + + wxSortedArray doesn't have this function because inserting in wrong place + would break its sorted condition. + + Please see wxArray::Add for explanation of the differences + between the overloaded versions of this function. + */ + void Insert(T item, size_t n, size_t copies = 1); + void Insert(T * item, size_t n); + void Insert(T & item, size_t n, size_t copies = 1); + //@} + + /** + Returns @true if the array is empty, @false otherwise. + */ + bool IsEmpty(); + + /** + Returns the item at the given position in the array. If @e index is out of + bounds, an assert failure is raised in the debug builds but nothing special is + done in the release build. + + The returned value is of type "reference to the array element type" for all of + the array classes. + */ + T Item(size_t index); + + /** + 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. + */ + T Last(); + + /** + To use an array you must first define the array class. This is done with the + help of the macros in this section. The class of array elements must be (at + least) forward declared for WX_DEFINE_ARRAY, WX_DEFINE_SORTED_ARRAY and + WX_DECLARE_OBJARRAY macros and must be fully declared before you use + WX_DEFINE_OBJARRAY macro. + + WX_DEFINE_ARRAY + + WX_DEFINE_EXPORTED_ARRAY + + WX_DEFINE_USER_EXPORTED_ARRAY + + WX_DEFINE_SORTED_ARRAY + + WX_DEFINE_SORTED_EXPORTED_ARRAY + + WX_DEFINE_SORTED_USER_EXPORTED_ARRAY + + WX_DECLARE_EXPORTED_OBJARRAY + + WX_DECLARE_USER_EXPORTED_OBJARRAY + + WX_DEFINE_OBJARRAY + + WX_DEFINE_EXPORTED_OBJARRAY + + WX_DEFINE_USER_EXPORTED_OBJARRAY + + To slightly complicate the matters even further, the operator - defined by + default for the array iterators by these macros only makes sense if the array + element type is not a pointer itself and, although it still works, this + provokes warnings from some compilers and to avoid them you should use the + @c _PTR versions of the macros above. For example, to define an array of + pointers to @c double you should use: + Note that the above macros are generally only useful for + wxObject types. There are separate macros for declaring an array of a simple + type, + such as an int. + + The following simple types are supported: + + int + + long + + size_t + + double + + To create an array of a simple type, simply append the type you want in CAPS to + the array definition. + + For example, for an integer array, you'd use one of the following variants: + + WX_DEFINE_ARRAY_INT + + WX_DEFINE_EXPORTED_ARRAY_INT + + WX_DEFINE_USER_EXPORTED_ARRAY_INT + + WX_DEFINE_SORTED_ARRAY_INT + + WX_DEFINE_SORTED_EXPORTED_ARRAY_INT + + WX_DEFINE_SORTED_USER_EXPORTED_ARRAY_INT + */ + + + /** + Automatic array memory management is quite trivial: the array starts by + preallocating some minimal amount of memory (defined by + WX_ARRAY_DEFAULT_INITIAL_SIZE) and when further new items exhaust already + allocated memory it reallocates it adding 50% of the currently allocated + amount, but no more than some maximal number which is defined by + ARRAY_MAXSIZE_INCREMENT constant. Of course, this may lead to some memory + being wasted (ARRAY_MAXSIZE_INCREMENT in the worst case, i.e. 4Kb in the + current implementation), so the wxArray::Shrink function is + provided to deallocate the extra memory. The wxArray::Alloc + function can also be quite useful if you know in advance how many items you are + going to put in the array and will prevent the array code from reallocating the + memory more times than needed. + + wxArray::Alloc + + wxArray::Shrink + */ + + + /** + Functions in this section return the total number of array elements and allow to + retrieve them - possibly using just the C array indexing [] operator which + does exactly the same as wxArray::Item method. + + wxArray::GetCount + + wxArray::IsEmpty + + wxArray::Item + + wxArray::Last + */ + + + /** + Removes an element from the array by value: the first item of the + array equal to @e 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: + See also WX_CLEAR_ARRAY macro which deletes all + elements of a wxArray (supposed to contain pointers). + */ + Remove(T item); + + /** + Removes @e count elements starting at @e 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: + See also WX_CLEAR_ARRAY macro which deletes all + elements of a wxArray (supposed to contain pointers). + */ + RemoveAt(size_t index, size_t count = 1); + + /** + WX_CLEAR_ARRAY + + wxArray::Empty + + wxArray::Clear + + wxArray::RemoveAt + + wxArray::Remove + */ + + + /** + wxArray::Index + + wxArray::IndexForInsert + + wxArray::Sort + */ + + + /** + ) + + This function ensures that the number of array elements is at least + @e count. If the array has already @e count or more items, nothing is + done. Otherwise, @c count - GetCount() elements are added and initialized to + the value @e defval. + + @sa wxArray::GetCount + */ + void SetCount(size_t count); + + /** + Frees all memory unused by the array. If the program knows that no new items + will be added to the array it may call Shrink() to reduce its memory usage. + However, if a new item is added to the array, some extra memory will be + allocated again. + */ + void Shrink(); + + /** + The notation CMPFUNCT should be read as if we had the following declaration: + where @e T is the type of the array elements. I.e. it is a function returning + @e int which is passed two arguments of type @e T *. + + Sorts the array using the specified compare function: this function should + return a negative, zero or positive value according to whether the first element + passed to it is less than, equal to or greater than the second one. + + wxSortedArray doesn't have this function because it is always sorted. + */ + void Sort(CMPFUNC compareFunction); + + /** + This macro may be used to append all elements of the @e other array to the + @e array. The two arrays must be of the same type. + */ +#define void WX_APPEND_ARRAY(wxArray& array, wxArray& other) /* implementation is private */ + + /** + 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(). + */ +#define void WX_CLEAR_ARRAY(wxArray& array) /* implementation is private */ + + //@{ + /** + This macro declares a new object array class named @e name and containing + the elements of type @e 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: + You must use WX_DEFINE_OBJARRAY macro to define + the array class - otherwise you would get link errors. + */ + WX_DECLARE_OBJARRAY(T, name); + WX_DECLARE_EXPORTED_OBJARRAY(T, name); + WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name); + //@} + + //@{ + /** + This macro defines a new array class named @e name and containing the + elements of type @e 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: + Note that wxWidgets predefines the following standard array classes: @b + wxArrayInt, + @b wxArrayLong, @b wxArrayShort, @b wxArrayDouble, @b wxArrayPtrVoid. + */ + WX_DEFINE_ARRAY(T, name); + WX_DEFINE_EXPORTED_ARRAY(T, name); + WX_DEFINE_USER_EXPORTED_ARRAY(T, name, exportspec); + //@} + + //@{ + /** + This macro defines the methods of the array class @e 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: + */ + WX_DEFINE_OBJARRAY(name); + WX_DEFINE_EXPORTED_OBJARRAY(name); + WX_DEFINE_USER_EXPORTED_OBJARRAY(name); + //@} + + //@{ + /** + This macro defines a new sorted array class named @e name and containing + the elements of type @e 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: + You will have to initialize the objects of this class by passing a comparison + function to the array object constructor like this: + */ + WX_DEFINE_SORTED_ARRAY(T, name); + WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name); + WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name); + //@} + + /** + This macro may be used to prepend all elements of the @e other array to the + @e array. The two arrays must be of the same type. + */ +#define void WX_PREPEND_ARRAY(wxArray& array, wxArray& other) /* implementation is private */ + + //@{ + /** + 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. + */ + wxArray(const wxArray& array); + wxSortedArray(const wxSortedArray& array); + wxObjArray(const wxObjArray& array); + wxArray operator=(const wxArray& array); + wxSortedArray operator=(const wxSortedArray& array); + wxObjArray operator=(const wxObjArray& array); + //@} + + //@{ + /** + 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. + */ + ~wxArray(); + ~wxSortedArray(); + ~wxObjArray(); + //@} +}; diff --git a/interface/dynlib.h b/interface/dynlib.h new file mode 100644 index 0000000000..2553defa84 --- /dev/null +++ b/interface/dynlib.h @@ -0,0 +1,415 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dynlib.h +// Purpose: documentation for wxDynamicLibraryDetails class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDynamicLibraryDetails + @wxheader{dynlib.h} + + 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. + + @library{wxbase} + @category{FIXME} +*/ +class wxDynamicLibraryDetails +{ +public: + /** + Retrieves the load address and the size of this module. + + @param addr + the pointer to the location to return load address in, may be + @NULL + + @param len + pointer to the location to return the size of this module in + memory in, may be @NULL + + @returns @true if the load address and module size were retrieved, @false + if this information is not available. + */ + bool GetAddress(void ** addr, size_t len); + + /** + Returns the base name of this module, e.g. @c kernel32.dll or + @c libc-2.3.2.so. + */ + wxString GetName(); + + /** + Returns the full path of this module if available, e.g. + @c c:\windows\system32\kernel32.dll or + @c /lib/libc-2.3.2.so. + */ + wxString GetPath(); + + /** + Returns the version of this module, e.g. @c 5.2.3790.0 or + @c 2.3.2. The returned string is empty if the version information is not + available. + */ + wxString GetVersion(); +}; + + +/** + @class wxDllLoader + @wxheader{dynlib.h} + + @b 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 @c 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 @e DLL and @e shared library/object will both be used in the + documentation to refer to the same thing: a @c .dll file under Windows or + @c .so or @c .sl one under Unix. + + Example of using this class to dynamically load the @c strlen() function: + + @code + #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); + } + @endcode + + @library{wxbase} + @category{appmanagement} +*/ +class wxDllLoader +{ +public: + /** + 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 @c ".dll" under Windows or (usually) + @c ".so" under Unix. + */ + static wxString GetDllExt(); + + /** + 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). + + @b NB: This function is Unix specific. It will always fail under Windows + or OS/2. + */ + wxDllType GetProgramHandle(); + + /** + 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. + + @param dllHandle + Valid handle previously returned by + LoadLibrary + + @param name + Name of the symbol. + */ + void * GetSymbol(wxDllType dllHandle, const wxString& name); + + /** + This function loads a shared library into memory, with @e 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 @e success parameter to test if it + is valid. If the handle is valid, the library must be unloaded later with + UnloadLibrary(). + + @param libname + Name of the shared object to load. + + @param success + May point to a bool variable which will be set to @true or + @false; may also be @NULL. + */ + wxDllType LoadLibrary(const wxString & libname, + bool* success = @NULL); + + /** + This function unloads the shared library. The handle @e dllhandle must have + been returned by LoadLibrary() previously. + */ + void UnloadLibrary(wxDllType dllhandle); +}; + + +/** + @class wxDynamicLibrary + @wxheader{dynlib.h} + + wxDynamicLibrary is a class representing dynamically loadable library + (Windows DLL, shared library under Unix etc.). Just create an object of + this class to load a library and don't worry about unloading it -- it will be + done in the objects destructor automatically. + + @library{wxbase} + @category{FIXME} + + @seealso + wxDynamicLibrary::CanonicalizePluginName +*/ +class wxDynamicLibrary +{ +public: + //@{ + /** + Constructor. Second form calls Load(). + */ + wxDynamicLibrary(); + wxDynamicLibrary(const wxString& name, + int flags = wxDL_DEFAULT); + //@} + + /** + Returns the platform-specific full name for the library called @e name. E.g. + it adds a @c ".dll" extension under Windows and @c "lib" prefix and + @c ".so", @c ".sl" or maybe @c ".dylib" extension under Unix. + + The possible values for @e cat are: + + + + wxDL_LIBRARY + + + normal library + + + + wxDL_MODULE + + + a loadable module or plugin + + + @sa CanonicalizePluginName() + */ + static wxString CanonicalizeName(const wxString& name, + wxDynamicLibraryCategory cat = wxDL_LIBRARY); + + /** + This function does the same thing as + CanonicalizeName() but for wxWidgets + plugins. The only difference is that compiler and version information are added + to the name to ensure that the plugin which is going to be loaded will be + compatible with the main program. + + The possible values for @e cat are: + + + + wxDL_PLUGIN_GUI + + + plugin which uses GUI classes (default) + + + + wxDL_PLUGIN_BASE + + + plugin which only uses wxBase + */ + static wxString CanonicalizePluginName(const wxString& name, + wxPluginCategory cat = wxDL_PLUGIN_GUI); + + /** + Detaches this object from its library handle, i.e. the object will not unload + the library any longer in its destructor but it is now the callers + responsibility to do this using Unload(). + */ + wxDllType Detach(); + + /** + Return a valid handle for the main program itself or @NULL if symbols + from the main program can't be loaded on this platform. + */ + static wxDllType GetProgramHandle(); + + /** + Returns pointer to symbol @e name in the library or @NULL if the library + contains no such symbol. + + @sa wxDYNLIB_FUNCTION + */ + void * GetSymbol(const wxString& name); + + /** + This function is available only under Windows as it is only useful when + dynamically loading symbols from standard Windows DLLs. Such functions have + either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide + character build) suffix if they take string parameters. Using this function you + can use just the base name of the function and the correct suffix is appende + automatically depending on the current build. Otherwise, this method is + identical to GetSymbol(). + */ + void * GetSymbolAorW(const wxString& name); + + /** + Returns @true if the symbol with the given @e 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. + + This function is new since wxWidgets version 2.5.4 + */ + bool HasSymbol(const wxString& name); + + /** + Returns @true if the library was successfully loaded, @false otherwise. + */ + bool IsLoaded(); + + /** + 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 @c 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. + */ + static wxDynamicLibraryDetailsArray ListLoaded(); + + /** + Loads DLL with the given @e name into memory. The @e 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 + + wxDL_QUIET + + + don't log an error message if the library couldn't be + loaded. + + Returns @true if the library was successfully loaded, @false otherwise. + */ + bool Load(const wxString& name, int flags = wxDL_DEFAULT); + + //@{ + /** + Unloads the library from memory. wxDynamicLibrary object automatically calls + this method from its destructor if it had been successfully loaded. + + 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. + */ + void Unload(); + static void Unload(wxDllType handle); + //@} +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + When loading a function from a DLL you always have to cast the returned + @c void * pointer to the correct type and, even more annoyingly, you have to + repeat this type twice if you want to declare and define a function pointer all + in one line + + This macro makes this slightly less painful by allowing you to specify the + type only once, as the first parameter, and creating a variable of this type + named after the function but with @c pfn prefix and initialized with the + function @e name from the wxDynamicLibrary + @e dynlib. + + @param type + the type of the function + + @param name + the name of the function to load, not a string (without quotes, + it is quoted automatically by the macro) + + @param dynlib + the library to load the function from +*/ +#define wxDYNLIB_FUNCTION(type, name, dynlib) /* implementation is private */ + diff --git a/interface/editlbox.h b/interface/editlbox.h new file mode 100644 index 0000000000..9f62c0cd8f --- /dev/null +++ b/interface/editlbox.h @@ -0,0 +1,95 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: editlbox.h +// Purpose: documentation for wxEditableListBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxEditableListBox + @wxheader{editlbox.h} + + An editable listbox is composite control that lets the + user easily enter, delete and reorder a list of strings. + + @beginStyleTable + @style{wxEL_ALLOW_NEW}: + Allows the user to enter new strings. + @style{wxEL_ALLOW_EDIT}: + Allows the user to edit existing strings. + @style{wxEL_ALLOW_DELETE}: + Allows the user to delete existing strings. + @style{wxEL_NO_REORDER}: + Does not allow the user to reorder the strings. + @style{wxEL_DEFAULT_STYLE}: + wxEL_ALLOW_NEW|wxEL_ALLOW_EDIT|wxEL_ALLOW_DELETE + @endStyleTable + + @library{wxadv} + @category{FIXME} + + @seealso + wxListBox +*/ +class wxEditableListBox : public wxPanel +{ +public: + //@{ + /** + Constructor, creating and showing a list box. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param label + The text shown just before the list control. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param style + Window style. See wxEditableListBox. + + @param name + Window name. + + @sa Create() + */ + wxEditableListBox(); + wxEditableListBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxEL_DEFAULT_STYLE, + const wxString& name = "editableListBox"); + //@} + + /** + Destructor, destroying the list box. + */ + ~wxEditableListBox(); + + /** + Creates the editable listbox for two-step construction. See wxEditableListBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxEL_DEFAULT_STYLE, + const wxString& name = "editableListBox"); + + /** + Replaces current contents with given strings. + */ + void SetStrings(const wxArrayString& strings); +}; diff --git a/interface/encconv.h b/interface/encconv.h new file mode 100644 index 0000000000..1eef341a94 --- /dev/null +++ b/interface/encconv.h @@ -0,0 +1,129 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: encconv.h +// Purpose: documentation for wxEncodingConverter class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxEncodingConverter + @wxheader{encconv.h} + + This class is capable of converting strings between two + 8-bit encodings/charsets. It can also convert from/to Unicode (but only + if you compiled wxWidgets with wxUSE_WCHAR_T set to 1). Only a limited subset + of encodings is supported by wxEncodingConverter: + @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and + @c wxFONTENCODING_KOI8. + + @library{wxbase} + @category{misc} + + @seealso + wxFontMapper, wxMBConv, @ref overview_nonenglishoverview "Writing non-English + applications" +*/ +class wxEncodingConverter : public wxObject +{ +public: + /** + Constructor. + */ + wxEncodingConverter(); + + /** + Return @true if (any text in) multibyte encoding @e encIn can be converted to + another one (@e encOut) losslessly. + + Do not call this method with @c wxFONTENCODING_UNICODE as either + parameter, it doesn't make sense (always works in one sense and always depends + on the text to convert in the other). + */ + static bool CanConvert(wxFontEncoding encIn, + wxFontEncoding encOut); + + //@{ + /** + Convert wxString and return new wxString object. + */ + bool Convert(const char* input, char* output); + bool Convert(const wchar_t* input, wchar_t* output); + bool Convert(const char* input, wchar_t* output); + bool Convert(const wchar_t* input, char* output); + bool Convert(char* str); + bool Convert(wchar_t* str); + wxString Convert(const wxString& input); + //@} + + /** + 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 @e enc + is in the array, + it is the very first item in it. + */ + static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc); + + /** + Return equivalents for given font that are used + under given platform. Supported platforms: + + wxPLATFORM_UNIX + wxPLATFORM_WINDOWS + wxPLATFORM_OS2 + wxPLATFORM_MAC + wxPLATFORM_CURRENT + + wxPLATFORM_CURRENT means the platform this binary was compiled for. + + Examples: + Equivalence is defined in terms of convertibility: + two encodings are equivalent if you can convert text between + then without losing information (it may - and will - happen + that you lose special chars like quotation marks or em-dashes + but you shouldn't lose any diacritics and language-specific + characters when converting between equivalent encodings). + + Remember that this function does @b NOT check for presence of + fonts in system. It only tells you what are most suitable + encodings. (It usually returns only one encoding.) + */ + static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc, + int platform = wxPLATFORM_CURRENT); + + /** + 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 @e input_enc encoding and will output string in + @e 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. + @e Method affects behaviour of Convert() in case input character + cannot be converted because it does not exist in output encoding: + + @b wxCONVERT_STRICT + + + follow behaviour of GNU Recode - + just copy unconvertible characters to output and don't change them + (its integer value will stay the same) + + @b wxCONVERT_SUBSTITUTE + + + try some (lossy) substitutions + - e.g. replace unconvertible latin capitals with acute by ordinary + capitals, replace en-dash or em-dash by '-' etc. + + Both modes guarantee that output string will have same length + as input string. + */ + bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc, + int method = wxCONVERT_STRICT); +}; diff --git a/interface/event.h b/interface/event.h new file mode 100644 index 0000000000..35f756078a --- /dev/null +++ b/interface/event.h @@ -0,0 +1,2857 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: event.h +// Purpose: documentation for wxKeyEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxKeyEvent + @wxheader{event.h} + + This event class contains information about keypress (character) events. + + Notice that there are three different kinds of keyboard events in wxWidgets: + key down and up events and char events. The difference between the first two + is clear - the first corresponds to a key press and the second to a key + release - otherwise they are identical. Just note that if the key is + maintained in a pressed state you will typically get a lot of (automatically + generated) down events but only one up so it is wrong to assume that there is + one up event corresponding to each down one. + + Both key events provide untranslated key codes while the char event carries + the translated one. The untranslated code for alphanumeric keys is always + an upper case value. For the other keys it is one of @c WXK_XXX values + from the @ref overview_keycodes "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 @c 'A' key is pressed, the key down + event key code is equal to @c ASCII A == 65. But the char event key code + is @c ASCII a == 97. On the other hand, if you press both SHIFT and + @c 'A' keys simultaneously , the key code in key down event will still be + just @c 'A' while the char event key code parameter will now be @c 'A' + as well. + + Although in this simple case it is clear that the correct key code could be + found in the key down event handler by checking the value returned by + wxKeyEvent::ShiftDown, in general you should use + @c EVT_CHAR for this as for non-alphanumeric keys the translation is + keyboard-layout dependent and can only be done properly by the system itself. + + Another kind of translation is done when the control key is pressed: for + example, for CTRL-A key press the key down event still carries the + same key code @c 'a' as usual but the char event will have key code of + 1, the ASCII value of this key combination. + + You may discover how the other keys on your system behave interactively by + running the text wxWidgets sample and pressing some keys + in any of the text controls shown in it. + + @b Note: If a key down (@c EVT_KEY_DOWN) event is caught and + the event handler does not call @c event.Skip() then the corresponding + char event (@c EVT_CHAR) will not happen. This is by design and + enables the programs that handle both types of events to be a bit + simpler. + + @b Note for Windows programmers: The key and char events in wxWidgets are + similar to but slightly different from Windows @c WM_KEYDOWN and + @c WM_CHAR events. In particular, Alt-x combination will generate a char + event in wxWidgets (unless it is used as an accelerator). + + @b Tip: be sure to call @c event.Skip() for events that you don't process in + key event function, otherwise menu shortcuts may cease to work under Windows. + + @library{wxcore} + @category{events} +*/ +class wxKeyEvent : public wxEvent +{ +public: + /** + Constructor. Currently, the only valid event types are wxEVT_CHAR and + wxEVT_CHAR_HOOK. + */ + wxKeyEvent(WXTYPE keyEventType); + + /** + Returns @true if the Alt key was down at the time of the key event. + + Notice that GetModifiers() is easier to use + correctly than this function so you should consider using it in new code. + */ + bool AltDown(); + + /** + CMD is a pseudo key which is the same as Control for PC and Unix + platforms but the special APPLE (a.k.a as COMMAND) key under + Macs: it makes often sense to use it instead of, say, ControlDown() because Cmd + key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still + exists, just not used for this purpose under Mac). So for non-Mac platforms + this is the same as ControlDown() and under + Mac this is the same as MetaDown(). + */ + bool CmdDown(); + + /** + Returns @true if the control key was down at the time of the key event. + + Notice that GetModifiers() is easier to use + correctly than this function so you should consider using it in new code. + */ + bool ControlDown(); + + /** + Returns the virtual key code. ASCII events return normal ASCII values, + while non-ASCII events return values such as @b WXK_LEFT for the + left cursor key. See Keycodes for a full list of + the virtual key codes. + + Note that in Unicode build, the returned value is meaningful only if the + user entered a character that can be represented in current locale's default + charset. You can obtain the corresponding Unicode character using + GetUnicodeKey(). + */ + int GetKeyCode(); + + /** + Return the bitmask of modifier keys which were pressed when this event + happened. See @ref overview_keymodifiers "key modifier constants" for the full + list + of modifiers. + + Notice that this function is easier to use correctly than, for example, + ControlDown() because when using the latter you + also have to remember to test that none of the other modifiers is pressed: + and forgetting to do it can result in serious program bugs (e.g. program not + working with European keyboard layout where ALTGR key which is seen by + the program as combination of CTRL and ALT is used). On the + other hand, you can simply write + with this function. + */ + int GetModifiers(); + + //@{ + /** + Obtains the position (in client coordinates) at which the key was pressed. + */ + wxPoint GetPosition(); + void GetPosition(long * x, long * y); + //@} + + /** + Returns the raw key code for this event. This is a platform-dependent scan code + which should only be used in advanced applications. + + @b NB: Currently the raw key codes are not supported by all ports, use + @c #ifdef wxHAS_RAW_KEY_CODES to determine if this feature is available. + */ + wxUint32 GetRawKeyCode(); + + /** + Returns the low level key flags for this event. The flags are + platform-dependent and should only be used in advanced applications. + + @b NB: Currently the raw key flags are not supported by all ports, use + @c #ifdef wxHAS_RAW_KEY_CODES to determine if this feature is available. + */ + wxUint32 GetRawKeyFlags(); + + /** + Returns the Unicode character corresponding to this key event. + + This function is only available in Unicode build, i.e. when + @c wxUSE_UNICODE is 1. + */ + wxChar GetUnicodeKey(); + + /** + Returns the X position (in client coordinates) of the event. + */ +#define long GetX() /* implementation is private */ + + /** + Returns the Y (in client coordinates) position of the event. + */ +#define long GetY() /* implementation is private */ + + /** + Returns @true if either CTRL or ALT keys was down + at the time of the key event. Note that this function does not take into + account neither SHIFT nor META key states (the reason for ignoring + the latter is that it is common for NUMLOCK key to be configured as + META under X but the key presses even while NUMLOCK is on should + be still processed normally). + */ + bool HasModifiers(); + + /** + Returns @true if the Meta key was down at the time of the key event. + + Notice that GetModifiers() is easier to use + correctly than this function so you should consider using it in new code. + */ + bool MetaDown(); + + /** + Returns @true if the shift key was down at the time of the key event. + + Notice that GetModifiers() is easier to use + correctly than this function so you should consider using it in new code. + */ + bool ShiftDown(); + + /** + bool m_altDown + + @b Deprecated: Please use GetModifiers() + instead! + + @true if the Alt key is pressed down. + */ + + + /** + bool m_controlDown + + @b Deprecated: Please use GetModifiers() + instead! + + @true if control is pressed down. + */ + + + /** + long m_keyCode + + @b Deprecated: Please use GetKeyCode() + instead! + + Virtual keycode. See Keycodes for a list of identifiers. + */ + + + /** + bool m_metaDown + + @b Deprecated: Please use GetModifiers() + instead! + + @true if the Meta key is pressed down. + */ + + + /** + bool m_shiftDown + + @b Deprecated: Please use GetModifiers() + instead! + + @true if shift is pressed down. + */ + + + /** + int m_x + + @b Deprecated: Please use GetX() instead! + + X position of the event. + */ + + + /** + int m_y + + @b Deprecated: Please use GetY() instead! + + Y position of the event. + */ +}; + + +/** + @class wxJoystickEvent + @wxheader{event.h} + + This event class contains information about mouse events, particularly + events received by windows. + + @library{wxcore} + @category{events} + + @seealso + wxJoystick +*/ +class wxJoystickEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxJoystickEvent(WXTYPE eventType = 0, int state = 0, + int joystick = wxJOYSTICK1, + int change = 0); + + /** + Returns @true if the event was a down event from the specified button (or any + button). + + @param button + Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + indicate any button down event. + */ + bool ButtonDown(int button = wxJOY_BUTTON_ANY); + + /** + Returns @true if the specified button (or any button) was in a down state. + + @param button + Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + indicate any button down event. + */ + bool ButtonIsDown(int button = wxJOY_BUTTON_ANY); + + /** + Returns @true if the event was an up event from the specified button (or any + button). + + @param button + Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to + indicate any button down event. + */ + bool ButtonUp(int button = wxJOY_BUTTON_ANY); + + /** + Returns the identifier of the button changing state. This is a wxJOY_BUTTONn + identifier, where + n is one of 1, 2, 3, 4. + */ + int GetButtonChange(); + + /** + Returns the down state of the buttons. This is a bitlist of wxJOY_BUTTONn + identifiers, where + n is one of 1, 2, 3, 4. + */ + int GetButtonState(); + + /** + Returns the identifier of the joystick generating the event - one of + wxJOYSTICK1 and wxJOYSTICK2. + */ + int GetJoystick(); + + /** + Returns the x, y position of the joystick event. + */ + wxPoint GetPosition(); + + /** + Returns the z position of the joystick event. + */ + int GetZPosition(); + + /** + Returns @true if this was a button up or down event (@e not 'is any button + down?'). + */ + bool IsButton(); + + /** + Returns @true if this was an x, y move event. + */ + bool IsMove(); + + /** + Returns @true if this was a z move event. + */ + bool IsZMove(); +}; + + +/** + @class wxScrollWinEvent + @wxheader{event.h} + + A scroll event holds information about events sent from scrolling windows. + + @library{wxcore} + @category{events} + + @seealso + wxScrollEvent, @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxScrollWinEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxScrollWinEvent(WXTYPE commandType = 0, int pos = 0, + int orientation = 0); + + /** + Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the + scrollbar. + */ + int GetOrientation(); + + /** + Returns the position of the scrollbar for the thumb track and release events. + Note that this field can't be used for the other events, you need to query + the window itself for the current position in that case. + */ + int GetPosition(); +}; + + +/** + @class wxSysColourChangedEvent + @wxheader{event.h} + + This class is used for system colour change events, which are generated + when the user changes the colour settings using the control panel. + This is only appropriate under Windows. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxSysColourChangedEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxSysColourChangedEvent(); +}; + + +/** + @class wxWindowCreateEvent + @wxheader{event.h} + + This event is sent just after the actual window associated with a wxWindow + object + has been created. Since it is derived from wxCommandEvent, the event propagates + up + the window hierarchy. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", + wxWindowDestroyEvent +*/ +class wxWindowCreateEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxWindowCreateEvent(wxWindow* win = @NULL); +}; + + +/** + @class wxPaintEvent + @wxheader{event.h} + + A paint event is sent when a window's contents needs to be repainted. + + Please notice that in general it is impossible to change the drawing of a + standard control (such as wxButton) and so you shouldn't + attempt to handle paint events for them as even if it might work on some + platforms, this is inherently not portable and won't work everywhere. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxPaintEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxPaintEvent(int id = 0); +}; + + +/** + @class wxMaximizeEvent + @wxheader{event.h} + + An event being sent when a top level window is maximized. Notice that it is + not sent when the window is restored to its original size after it had been + maximized, only a normal wxSizeEvent is generated in + this case. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", + wxTopLevelWindow::Maximize, wxTopLevelWindow::IsMaximized +*/ +class wxMaximizeEvent : public wxEvent +{ +public: + /** + Constructor. Only used by wxWidgets internally. + */ + wxMaximizeEvent(int id = 0); +}; + + +/** + @class wxUpdateUIEvent + @wxheader{event.h} + + This class is used for pseudo-events which are called by wxWidgets + to give an application the chance to update various user interface elements. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxUpdateUIEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxUpdateUIEvent(wxWindowID commandId = 0); + + /** + Returns @true if it is appropriate to update (send UI update events to) + this window. + + This function looks at the mode used (see wxUpdateUIEvent::SetMode), + the wxWS_EX_PROCESS_UI_UPDATES flag in @e window, + the time update events were last sent in idle time, and + the update interval, to determine whether events should be sent to + this window now. By default this will always return @true because + the update mode is initially wxUPDATE_UI_PROCESS_ALL and + the interval is set to 0; so update events will be sent as + often as possible. You can reduce the frequency that events + are sent by changing the mode and/or setting an update interval. + + @sa ResetUpdateTime(), SetUpdateInterval(), + SetMode() + */ + static bool CanUpdate(wxWindow* window); + + /** + Check or uncheck the UI element. + */ + void Check(bool check); + + /** + Enable or disable the UI element. + */ + void Enable(bool enable); + + /** + Returns @true if the UI element should be checked. + */ + bool GetChecked(); + + /** + Returns @true if the UI element should be enabled. + */ + bool GetEnabled(); + + /** + Static function returning a value specifying how wxWidgets + will send update events: to all windows, or only to those which specify that + they + will process the events. + + See SetMode(). + */ + static wxUpdateUIMode GetMode(); + + /** + Returns @true if the application has called Check(). For wxWidgets internal use + only. + */ + bool GetSetChecked(); + + /** + Returns @true if the application has called Enable(). For wxWidgets internal use + only. + */ + bool GetSetEnabled(); + + /** + Returns @true if the application has called Show(). For wxWidgets internal use + only. + */ + bool GetSetShown(); + + /** + Returns @true if the application has called SetText(). For wxWidgets internal + use only. + */ + bool GetSetText(); + + /** + Returns @true if the UI element should be shown. + */ + bool GetShown(); + + /** + Returns the text that should be set for the UI element. + */ + wxString GetText(); + + /** + Returns the current interval between updates in milliseconds. + -1 disables updates, 0 updates as frequently as possible. + + See SetUpdateInterval(). + */ + static long GetUpdateInterval(); + + /** + Used internally to reset the last-updated time to the + current time. It is assumed that update events are + normally sent in idle time, so this is called at the end of + idle processing. + + @sa CanUpdate(), SetUpdateInterval(), + SetMode() + */ + static void ResetUpdateTime(); + + /** + Specify how wxWidgets will send update events: to + all windows, or only to those which specify that they + will process the events. + + @e mode may be one of the following values. + The default is wxUPDATE_UI_PROCESS_ALL. + */ + static void SetMode(wxUpdateUIMode mode); + + /** + Sets the text for this UI element. + */ + void SetText(const wxString& text); + + /** + Sets the interval between updates in milliseconds. + Set to -1 to disable updates, or to 0 to update as frequently as possible. + The default is 0. + + Use this to reduce the overhead of UI update events if your application + has a lot of windows. If you set the value to -1 or greater than 0, + you may also need to call wxWindow::UpdateWindowUI + at appropriate points in your application, such as when a dialog + is about to be shown. + */ + static void SetUpdateInterval(long updateInterval); + + /** + Show or hide the UI element. + */ + void Show(bool show); +}; + + +/** + @class wxClipboardTextEvent + @wxheader{event.h} + + This class represents the events generated by a control (typically a + wxTextCtrl but other windows can generate these events as + well) when its content gets copied or cut to, or pasted from the clipboard. + There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY, + wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE. + + If any of these events is processed (without being skipped) by an event + handler, the corresponding operation doesn't take place which allows to prevent + the text from being copied from or pasted to a control. It is also possible to + examine the clipboard contents in the PASTE event handler and transform it in + some way before inserting in a control -- for example, changing its case or + removing invalid characters. + + Finally notice that a CUT event is always preceded by the COPY event which + makes it possible to only process the latter if it doesn't matter if the text + was copied or cut. + + @library{wxcore} + @category{events} + + @seealso + wxClipboard +*/ +class wxClipboardTextEvent : public wxCommandEvent +{ +public: + /** + + */ + wxClipboardTextEvent(wxEventType commandType = wxEVT_@NULL, + int id = 0); +}; + + +/** + @class wxMouseEvent + @wxheader{event.h} + + This event class contains information about the events generated by the mouse: + they include mouse buttons press and release events and mouse move events. + + All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the + left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and + @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more + buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events + can also be generated. Note that not all mice have even a middle button so a + portable application should avoid relying on the events from it (but the right + button click can be emulated using the left mouse button with the control key + under Mac platforms with a single button mouse). + + For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events + purposes, the mouse is considered to be inside the window if it is in the + window client area and not inside one of its children. In other words, the + parent window receives @c wxEVT_LEAVE_WINDOW event not only when the + mouse leaves the window entirely but also when it enters one of its children. + + @b NB: Note that under Windows CE mouse enter and leave events are not natively + supported + by the system but are generated by wxWidgets itself. This has several + drawbacks: the LEAVE_WINDOW event might be received some time after the mouse + left the window and the state variables for it may have changed during this + time. + + @b NB: Note the difference between methods like + wxMouseEvent::LeftDown and + wxMouseEvent::LeftIsDown: the former returns @true + when the event corresponds to the left mouse button click while the latter + returns @true if the left mouse button is currently being pressed. For + example, when the user is dragging the mouse you can use + wxMouseEvent::LeftIsDown to test + whether the left mouse button is (still) depressed. Also, by convention, if + wxMouseEvent::LeftDown returns @true, + wxMouseEvent::LeftIsDown will also return @true in + wxWidgets whatever the underlying GUI behaviour is (which is + platform-dependent). The same applies, of course, to other mouse buttons as + well. + + @library{wxcore} + @category{events} + + @seealso + wxKeyEvent::CmdDown +*/ +class wxMouseEvent : public wxEvent +{ +public: + /** + Constructor. Valid event types are: + + @b wxEVT_ENTER_WINDOW + @b wxEVT_LEAVE_WINDOW + @b wxEVT_LEFT_DOWN + @b wxEVT_LEFT_UP + @b wxEVT_LEFT_DCLICK + @b wxEVT_MIDDLE_DOWN + @b wxEVT_MIDDLE_UP + @b wxEVT_MIDDLE_DCLICK + @b wxEVT_RIGHT_DOWN + @b wxEVT_RIGHT_UP + @b wxEVT_RIGHT_DCLICK + @b wxEVT_MOUSE_AUX1_DOWN + @b wxEVT_MOUSE_AUX1_UP + @b wxEVT_MOUSE_AUX1_DCLICK + @b wxEVT_MOUSE_AUX2_DOWN + @b wxEVT_MOUSE_AUX2_UP + @b wxEVT_MOUSE_AUX2_DCLICK + @b wxEVT_MOTION + @b wxEVT_MOUSEWHEEL + */ + wxMouseEvent(WXTYPE mouseEventType = 0); + + /** + Returns @true if the Alt key was down at the time of the event. + */ + bool AltDown(); + + /** + Returns @true if the event was a first extra button double click. + */ + bool Aux1DClick(); + + /** + Returns @true if the first extra button mouse button changed to down. + */ + bool Aux1Down(); + + /** + Returns @true if the first extra button mouse button is currently down, + independent + of the current event type. + */ + bool Aux1IsDown(); + + /** + Returns @true if the first extra button mouse button changed to up. + */ + bool Aux1Up(); + + /** + Returns @true if the event was a second extra button double click. + */ + bool Aux2DClick(); + + /** + Returns @true if the second extra button mouse button changed to down. + */ + bool Aux2Down(); + + /** + Returns @true if the second extra button mouse button is currently down, + independent + of the current event type. + */ + bool Aux2IsDown(); + + /** + Returns @true if the second extra button mouse button changed to up. + */ + bool Aux2Up(); + + /** + Returns @true if the identified mouse button is changing state. Valid + values of @e button are: + + @c wxMOUSE_BTN_LEFT + + + check if left button was pressed + + @c wxMOUSE_BTN_MIDDLE + + + check if middle button was pressed + + @c wxMOUSE_BTN_RIGHT + + + check if right button was pressed + + @c wxMOUSE_BTN_AUX1 + + + check if the first extra button was pressed + + @c wxMOUSE_BTN_AUX2 + + + check if the second extra button was pressed + + @c wxMOUSE_BTN_ANY + + + check if any button was pressed + */ + bool Button(int button); + + /** + If the argument is omitted, this returns @true if the event was a mouse + double click event. Otherwise the argument specifies which double click event + was generated (see Button() for the possible + values). + */ + bool ButtonDClick(int but = wxMOUSE_BTN_ANY); + + /** + If the argument is omitted, this returns @true if the event was a mouse + button down event. Otherwise the argument specifies which button-down event + was generated (see Button() for the possible + values). + */ + bool ButtonDown(int but = -1); + + /** + If the argument is omitted, this returns @true if the event was a mouse + button up event. Otherwise the argument specifies which button-up event + was generated (see Button() for the possible + values). + */ + bool ButtonUp(int but = -1); + + /** + Same as MetaDown() under Mac, same as + ControlDown() elsewhere. + + @sa wxKeyEvent::CmdDown + */ + bool CmdDown(); + + /** + Returns @true if the control key was down at the time of the event. + */ + bool ControlDown(); + + /** + Returns @true if this was a dragging event (motion while a button is depressed). + + @sa Moving() + */ + bool Dragging(); + + /** + Returns @true if the mouse was entering the window. + + See also Leaving(). + */ + bool Entering(); + + /** + Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE + if no button is involved (for mouse move, enter or leave event, for example). + Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and + double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT + for the same events for the middle and the right buttons respectively. + */ + int GetButton(); + + /** + Returns the number of mouse clicks for this event: 1 for a simple click, 2 + for a double-click, 3 for a triple-click and so on. + + Currently this function is implemented only in wxMac and returns -1 for the + other platforms (you can still distinguish simple clicks from double-clicks as + they generate different kinds of events however). + + This function is new since wxWidgets version 2.9.0 + */ + int GetClickCount(); + + /** + Returns the configured number of lines (or whatever) to be scrolled per + wheel action. Defaults to three. + */ + int GetLinesPerAction(); + + /** + Returns the logical mouse position in pixels (i.e. translated according to the + translation set for the DC, which usually indicates that the window has been + scrolled). + */ + wxPoint GetLogicalPosition(const wxDC& dc); + + //@{ + /** + Sets *x and *y to the position at which the event occurred. + + Returns the physical mouse position in pixels. + + Note that if the mouse event has been artificially generated from a special + keyboard combination (e.g. under Windows when the "menu'' key is pressed), the + returned position is @c wxDefaultPosition. + */ + wxPoint GetPosition(); + void GetPosition(wxCoord* x, wxCoord* y); + void GetPosition(long* x, long* y); + //@} + + /** + Get wheel delta, normally 120. This is the threshold for action to be + taken, and one such action (for example, scrolling one increment) + should occur for each delta. + */ + int GetWheelDelta(); + + /** + Get wheel rotation, positive or negative indicates direction of + rotation. Current devices all send an event when rotation is at least + +/-WheelDelta, but finer resolution devices can be created in the future. + Because of this you shouldn't assume that one event is equal to 1 line, but you + should be able to either do partial line scrolling or wait until several + events accumulate before scrolling. + */ + int GetWheelRotation(); + + /** + Returns X coordinate of the physical mouse event position. + */ +#define long GetX() /* implementation is private */ + + /** + Returns Y coordinate of the physical mouse event position. + */ +#define long GetY() /* implementation is private */ + + /** + Returns @true if the event was a mouse button event (not necessarily a button + down event - + that may be tested using @e ButtonDown). + */ + bool IsButton(); + + /** + Returns @true if the system has been setup to do page scrolling with + the mouse wheel instead of line scrolling. + */ + bool IsPageScroll(); + + /** + Returns @true if the mouse was leaving the window. + + See also Entering(). + */ + bool Leaving(); + + /** + Returns @true if the event was a left double click. + */ + bool LeftDClick(); + + /** + Returns @true if the left mouse button changed to down. + */ + bool LeftDown(); + + /** + Returns @true if the left mouse button is currently down, independent + of the current event type. + + Please notice that it is not the same as + LeftDown() which returns @true if the event was + generated by the left mouse button being pressed. Rather, it simply describes + the state of the left mouse button at the time when the event was generated + (so while it will be @true for a left click event, it can also be @true for + a right click if it happened while the left mouse button was pressed). + + This event is usually used in the mouse event handlers which process "move + mouse" messages to determine whether the user is (still) dragging the mouse. + */ + bool LeftIsDown(); + + /** + Returns @true if the left mouse button changed to up. + */ + bool LeftUp(); + + /** + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown(); + + /** + Returns @true if the event was a middle double click. + */ + bool MiddleDClick(); + + /** + Returns @true if the middle mouse button changed to down. + */ + bool MiddleDown(); + + /** + Returns @true if the middle mouse button is currently down, independent + of the current event type. + */ + bool MiddleIsDown(); + + /** + Returns @true if the middle mouse button changed to up. + */ + bool MiddleUp(); + + /** + Returns @true if this was a motion event and no mouse buttons were pressed. + If any mouse button is held pressed, then this method returns @false and + Dragging() returns @true. + */ + bool Moving(); + + /** + Returns @true if the event was a right double click. + */ + bool RightDClick(); + + /** + Returns @true if the right mouse button changed to down. + */ + bool RightDown(); + + /** + Returns @true if the right mouse button is currently down, independent + of the current event type. + */ + bool RightIsDown(); + + /** + Returns @true if the right mouse button changed to up. + */ + bool RightUp(); + + /** + Returns @true if the shift key was down at the time of the event. + */ + bool ShiftDown(); + + /** + bool m_altDown + + @true if the Alt key is pressed down. + */ + + + /** + bool m_controlDown + + @true if control key is pressed down. + */ + + + /** + bool m_leftDown + + @true if the left mouse button is currently pressed down. + */ + + + /** + int m_linesPerAction + + The configured number of lines (or whatever) to be scrolled per wheel + action. + */ + + + /** + bool m_metaDown + + @true if the Meta key is pressed down. + */ + + + /** + bool m_middleDown + + @true if the middle mouse button is currently pressed down. + */ + + + /** + bool m_rightDown + + @true if the right mouse button is currently pressed down. + */ + + + /** + bool m_shiftDown + + @true if shift is pressed down. + */ + + + /** + int m_wheelDelta + + The wheel delta, normally 120. + */ + + + /** + int m_wheelRotation + + The distance the mouse wheel is rotated. + */ + + + /** + long m_x + + X-coordinate of the event. + */ + + + /** + long m_y + + Y-coordinate of the event. + */ +}; + + +/** + @class wxDropFilesEvent + @wxheader{event.h} + + This class is used for drop files events, that is, when files have been dropped + onto the window. This functionality is currently only available under Windows. + The window must have previously been enabled for dropping by calling + wxWindow::DragAcceptFiles. + + Important note: this is a separate implementation to the more general + drag and drop implementation documented here. It uses the + older, Windows message-based approach of dropping files. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxDropFilesEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxDropFilesEvent(WXTYPE id = 0, int noFiles = 0, + wxString* files = @NULL); + + /** + Returns an array of filenames. + */ + wxString* GetFiles(); + + /** + Returns the number of files dropped. + */ + int GetNumberOfFiles(); + + /** + Returns the position at which the files were dropped. + + Returns an array of filenames. + */ + wxPoint GetPosition(); + + /** + wxString* m_files + + An array of filenames. + */ + + + /** + int m_noFiles + + The number of files dropped. + */ + + + /** + wxPoint m_pos + + The point at which the drop took place. + */ +}; + + +/** + @class wxCommandEvent + @wxheader{event.h} + + This event class contains information about command events, which originate + from a variety of + simple controls. More complex controls, such as wxTreeCtrl, have separate + command event classes. + + @library{wxcore} + @category{events} +*/ +class wxCommandEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxCommandEvent(WXTYPE commandEventType = 0, int id = 0); + + /** + Deprecated, use IsChecked() instead. + */ + bool Checked(); + + /** + Returns client data pointer for a listbox or choice selection event + (not valid for a deselection). + */ + void* GetClientData(); + + /** + Returns client object pointer for a listbox or choice selection event + (not valid for a deselection). + */ + wxClientData * GetClientObject(); + + /** + Returns extra information dependant on the event objects type. + If the event comes from a listbox selection, it is a boolean + determining whether the event was a selection (@true) or a + deselection (@false). A listbox deselection only occurs for + multiple-selection boxes, and in this case the index and string values + are indeterminate and the listbox must be examined by the application. + */ + long GetExtraLong(); + + /** + Returns the integer identifier corresponding to a listbox, choice or + radiobox selection (only if the event was a selection, not a + deselection), or a boolean value representing the value of a checkbox. + */ + int GetInt(); + + /** + Returns item index for a listbox or choice selection event (not valid for + a deselection). + */ + int GetSelection(); + + /** + Returns item string for a listbox or choice selection event (not valid for + a deselection). + */ + wxString GetString(); + + /** + This method can be used with checkbox and menu events: for the checkboxes, the + method returns @true for a selection event and @false for a + deselection one. For the menu events, this method indicates if the menu item + just has become checked or unchecked (and thus only makes sense for checkable + menu items). + + Notice that this method can not be used with + wxCheckListBox currently. + */ + bool IsChecked(); + + /** + For a listbox or similar event, returns @true if it is a selection, @false if it + is a deselection. + */ + bool IsSelection(); + + /** + Sets the client data for this event. + */ + void SetClientData(void* clientData); + + /** + Sets the client object for this event. The client object is not owned by the + event + object and the event object will not delete the client object in its destructor. + The client object must be owned and deleted by another object (e.g. a control) + that has longer life time than the event object. + */ + void SetClientObject(wxClientData* clientObject); + + /** + Sets the @b m_extraLong member. + */ + void SetExtraLong(long extraLong); + + /** + Sets the @b m_commandInt member. + */ + void SetInt(int intCommand); + + /** + Sets the @b m_commandString member. + */ + void SetString(const wxString& string); +}; + + +/** + @class wxActivateEvent + @wxheader{event.h} + + An activate event is sent when a window or application is being activated + or deactivated. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", wxApp::IsActive +*/ +class wxActivateEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxActivateEvent(WXTYPE eventType = 0, bool active = @true, + int id = 0); + + /** + Returns @true if the application or window is being activated, @false otherwise. + */ + bool GetActive(); +}; + + +/** + @class wxContextMenuEvent + @wxheader{event.h} + + This class is used for context menu events, sent to give + the application a chance to show a context (popup) menu. + + Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this + means that the event originated + from a keyboard context button event, and you should compute a suitable + position yourself, + for example by calling wxGetMousePosition. + + When a keyboard context menu button is pressed on Windows, a right-click event + with default position is sent first, + and if this event is not processed, the context menu event is sent. So if you + process mouse events and you find your context menu event handler + is not being called, you could call wxEvent::Skip for mouse right-down events. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_wxcommandevent "Command events", @ref + overview_eventhandlingoverview "Event handling overview" +*/ +class wxContextMenuEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxContextMenuEvent(WXTYPE id = 0, int id = 0, + const wxPoint& pos=wxDefaultPosition); + + /** + Returns the position in screen coordinates at which the menu should be shown. + Use wxWindow::ScreenToClient to + convert to client coordinates. You can also omit a position from + wxWindow::PopupMenu in order to use + the current mouse pointer position. + + If the event originated from a keyboard event, the value returned from this + function will be wxDefaultPosition. + */ + wxPoint GetPosition(); + + /** + Sets the position at which the menu should be shown. + */ + void SetPosition(const wxPoint& point); +}; + + +/** + @class wxEraseEvent + @wxheader{event.h} + + An erase event is sent when a window's background needs to be repainted. + + On some platforms, such as GTK+, this event is simulated (simply generated just + before the + paint event) and may cause flicker. It is therefore recommended that + you set the text background colour explicitly in order to prevent flicker. + The default background colour under GTK+ is grey. + + To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table + definition. + + You must call wxEraseEvent::GetDC and use the returned device context if it is + non-@NULL. + If it is @NULL, create your own temporary wxClientDC object. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxEraseEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxEraseEvent(int id = 0, wxDC* dc = @NULL); + + /** + Returns the device context associated with the erase event to draw on. + */ +#define wxDC* GetDC() /* implementation is private */ +}; + + +/** + @class wxFocusEvent + @wxheader{event.h} + + A focus event is sent when a window's focus changes. The window losing focus + receives a "kill focus'' event while the window gaining it gets a "set + focus'' one. + + Notice that the set focus event happens both when the user gives focus to the + window (whether using the mouse or keyboard) and when it is done from the + program itself using wxWindow::SetFocus. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxFocusEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxFocusEvent(WXTYPE eventType = 0, int id = 0); + + /** + Returns the window associated with this event, that is the window which had the + focus before for the @c wxEVT_SET_FOCUS event and the window which is + going to receive focus for the @c wxEVT_KILL_FOCUS one. + + Warning: the window pointer may be @NULL! + */ +}; + + +/** + @class wxChildFocusEvent + @wxheader{event.h} + + A child focus event is sent to a (parent-)window when one of its child windows + gains focus, + so that the window could restore the focus back to its corresponding child + if it loses it now and regains later. + + Notice that child window is the direct child of the window receiving event. + Use wxWindow::FindFocus to retreive the window which is actually getting focus. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxChildFocusEvent : public wxCommandEvent +{ +public: + /** + Constructor. + + @param win + The direct child which is (or which contains the window which is) receiving the + focus. + */ + wxChildFocusEvent(wxWindow * win = @NULL); + + /** + Returns the direct child which receives the focus, or a (grand-)parent of the + control receiving the focus. + + To get the actually focused control use wxWindow::FindFocus. + */ +}; + + +/** + @class wxMouseCaptureLostEvent + @wxheader{event.h} + + An mouse capture lost event is sent to a window that obtained mouse capture, + which was subsequently loss due to "external" event, for example when a dialog + box is shown or if another application captures the mouse. + + If this happens, this event is sent to all windows that are on capture stack + (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is + not sent if the capture changes because of a call to CaptureMouse or + ReleaseMouse. + + This event is currently emitted under Windows only. + + @library{wxcore} + @category{events} + + @seealso + wxMouseCaptureChangedEvent, @ref overview_eventhandlingoverview "Event handling + overview", wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture +*/ +class wxMouseCaptureLostEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxMouseCaptureLostEvent(wxWindowID windowId = 0); +}; + + +/** + @class wxNotifyEvent + @wxheader{event.h} + + This class is not used by the event handlers by itself, but is a base class + for other event classes (such as wxNotebookEvent). + + It (or an object of a derived class) is sent when the controls state is being + changed and allows the program to wxNotifyEvent::Veto this + change if it wants to prevent it from happening. + + @library{wxcore} + @category{events} + + @seealso + wxNotebookEvent +*/ +class wxNotifyEvent : public wxCommandEvent +{ +public: + /** + Constructor (used internally by wxWidgets only). + */ + wxNotifyEvent(wxEventType eventType = wxEVT_@NULL, int id = 0); + + /** + This is the opposite of Veto(): it explicitly + allows the event to be processed. For most events it is not necessary to call + this method as the events are allowed anyhow but some are forbidden by default + (this will be mentioned in the corresponding event description). + */ + void Allow(); + + /** + Returns @true if the change is allowed (Veto() + hasn't been called) or @false otherwise (if it was). + */ + bool IsAllowed(); + + /** + Prevents the change announced by this event from happening. + + It is in general a good idea to notify the user about the reasons for vetoing + the change because otherwise the applications behaviour (which just refuses to + do what the user wants) might be quite surprising. + */ + void Veto(); +}; + + +/** + @class wxHelpEvent + @wxheader{event.h} + + A help event is sent when the user has requested context-sensitive help. + This can either be caused by the application requesting + context-sensitive help mode via wxContextHelp, or + (on MS Windows) by the system generating a WM_HELP message when the user + pressed F1 or clicked + on the query button in a dialog caption. + + A help event is sent to the window that the user clicked on, and is propagated + up the + window hierarchy until the event is processed or there are no more event + handlers. + The application should call wxEvent::GetId to check the identity of the + clicked-on window, + and then either show some suitable help or call wxEvent::Skip if the identifier + is unrecognised. + Calling Skip is important because it allows wxWidgets to generate further + events for ancestors + of the clicked-on window. Otherwise it would be impossible to show help for + container windows, + since processing would stop after the first window found. + + @library{wxcore} + @category{FIXME} + + @seealso + wxContextHelp, wxDialog, @ref overview_eventhandlingoverview "Event handling + overview" +*/ +class wxHelpEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxHelpEvent(WXTYPE eventType = 0, wxWindowID id = 0, + const wxPoint& point); + + /** + Returns the origin of the help event which is one of the following values: + + + @b Origin_Unknown + + + Unrecognized event source. + + @b Origin_Keyboard + + + Event generated by @c F1 key press. + + @b Origin_HelpButton + + + Event generated by + wxContextHelp or using the "?" title bur button under + MS Windows. + + The application may handle events generated using the keyboard or mouse + differently, e.g. by using wxGetMousePosition + for the mouse events. + + @sa SetOrigin() + */ + wxHelpEvent::Origin GetOrigin(); + + /** + Returns the left-click position of the mouse, in screen coordinates. This allows + the application to position the help appropriately. + */ + const wxPoint GetPosition(); + + /** + Set the help event origin, only used internally by wxWidgets normally. + + @sa GetOrigin() + */ + void SetOrigin(wxHelpEvent::Origin origin); + + /** + Sets the left-click position of the mouse, in screen coordinates. + */ + void SetPosition(const wxPoint& pt); +}; + + +/** + @class wxScrollEvent + @wxheader{event.h} + + A scroll event holds information about events sent from stand-alone + scrollbars and sliders. Note that + starting from wxWidgets 2.1, scrolled windows send the + wxScrollWinEvent which does not derive from + wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of + events and use the event table macros mentioned below only for the + scrollbar-like controls. + + @library{wxcore} + @category{events} + + @seealso + wxScrollBar, wxSlider, wxSpinButton, , wxScrollWinEvent, @ref + overview_eventhandlingoverview "Event handling overview" +*/ +class wxScrollEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxScrollEvent(WXTYPE commandType = 0, int id = 0, int pos = 0, + int orientation = 0); + + /** + Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the + scrollbar. + */ + int GetOrientation(); + + /** + Returns the position of the scrollbar. + */ + int GetPosition(); +}; + + +/** + @class wxIdleEvent + @wxheader{event.h} + + This class is used for idle events, which are generated when the system becomes + idle. Note that, unless you do something specifically, the idle events are not + sent if the system remains idle once it has become it, e.g. only a single idle + event will be generated until something else resulting in more normal events + happens and only then is the next idle event sent again. If you need to ensure + a continuous stream of idle events, you can either use + wxIdleEvent::RequestMore method in your handler or call + wxWakeUpIdle periodically (for example from 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. + + @library{wxbase} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", wxUpdateUIEvent, + wxWindow::OnInternalIdle +*/ +class wxIdleEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxIdleEvent(); + + /** + Returns @true if it is appropriate to send idle events to + this window. + + This function looks at the mode used (see wxIdleEvent::SetMode), + and the wxWS_EX_PROCESS_IDLE style in @e 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. + + @sa SetMode() + */ + static bool CanSend(wxWindow* window); + + /** + Static function returning a value specifying how wxWidgets + will send idle events: to all windows, or only to those which specify that they + will process the events. + + See SetMode(). + */ + static wxIdleMode GetMode(); + + /** + Returns @true if the OnIdle function processing this event requested more + processing time. + + @sa RequestMore() + */ + bool MoreRequested(); + + /** + 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. + + @sa MoreRequested() + */ + void RequestMore(bool needMore = @true); + + /** + Static function for specifying how wxWidgets will send idle events: to + all windows, or only to those which specify that they + will process the events. + + @e mode can be one of the following values. + The default is wxIDLE_PROCESS_ALL. + */ + static void SetMode(wxIdleMode mode); +}; + + +/** + @class wxInitDialogEvent + @wxheader{event.h} + + A wxInitDialogEvent is sent as a dialog or panel is being initialised. + Handlers for this event can transfer data to the window. + The default handler calls wxWindow::TransferDataToWindow. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxInitDialogEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxInitDialogEvent(int id = 0); +}; + + +/** + @class wxWindowDestroyEvent + @wxheader{event.h} + + This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a + window is destroyed. + + When a class derived from wxWindow is destroyed its destructor will have + already run by the time this event is sent. Therefore this event will not + usually be received at all. + + To receive this event wxEvtHandler::Connect + must be used (using an event table macro will not work). Since it is + received after the destructor has run, an object should not handle its + own wxWindowDestroyEvent, but it can be used to get notification of the + destruction of another window. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", + wxWindowCreateEvent +*/ +class wxWindowDestroyEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxWindowDestroyEvent(wxWindow* win = @NULL); +}; + + +/** + @class wxNavigationKeyEvent + @wxheader{event.h} + + This event class contains information about navigation events, + generated by navigation keys such as tab and page down. + + This event is mainly used by wxWidgets implementations. A + wxNavigationKeyEvent handler is automatically provided by wxWidgets + when you make a class into a control container with the macro + WX_DECLARE_CONTROL_CONTAINER. + + @library{wxcore} + @category{events} + + @seealso + wxWindow::Navigate, wxWindow::NavigateIn +*/ +class wxNavigationKeyEvent +{ +public: + //@{ + /** + Constructor. + */ + wxNavigationKeyEvent(); + wxNavigationKeyEvent(const wxNavigationKeyEvent& event); + //@} + + /** + Returns the child that has the focus, or @NULL. + */ + wxWindow* GetCurrentFocus(); + + /** + Returns @true if the navigation was in the forward direction. + */ + bool GetDirection(); + + /** + Returns @true if the navigation event was from a tab key. This is required + for proper navigation over radio buttons. + */ + bool IsFromTab(); + + /** + Returns @true if the navigation event represents a window change (for + example, from Ctrl-Page Down + in a notebook). + */ + bool IsWindowChange(); + + /** + Sets the current focus window member. + */ + void SetCurrentFocus(wxWindow* currentFocus); + + /** + Sets the direction to forward if @e direction is @true, or backward if @c + @false. + */ + void SetDirection(bool direction); + + /** + Sets the flags. + */ + void SetFlags(long flags); + + /** + Marks the navigation event as from a tab key. + */ + void SetFromTab(bool fromTab); + + /** + Marks the event as a window change event. + */ + void SetWindowChange(bool windowChange); +}; + + +/** + @class wxMouseCaptureChangedEvent + @wxheader{event.h} + + An mouse capture changed event is sent to a window that loses its + mouse capture. This is called even if wxWindow::ReleaseCapture + was called by the application code. Handling this event allows + an application to cater for unexpected capture releases which + might otherwise confuse mouse handling code. + + This event is implemented under Windows only. + + @library{wxcore} + @category{events} + + @seealso + wxMouseCaptureLostEvent, @ref overview_eventhandlingoverview "Event handling + overview", wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture +*/ +class wxMouseCaptureChangedEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxMouseCaptureChangedEvent(wxWindowID windowId = 0, + wxWindow* gainedCapture = @NULL); + + /** + Returns the window that gained the capture, or @NULL if it was a non-wxWidgets + window. + */ + wxWindow* GetCapturedWindow(); +}; + + +/** + @class wxCloseEvent + @wxheader{event.h} + + This event class contains information about window and session close events. + + The handler function for EVT_CLOSE is called when the user has tried to close a + a frame + or dialog box using the window manager (X) or system menu (Windows). It can + also be invoked by the application itself programmatically, for example by + calling the wxWindow::Close function. + + You should check whether the application is forcing the deletion of the window + using wxCloseEvent::CanVeto. If this is @false, + you @e must destroy the window using wxWindow::Destroy. + If the return value is @true, it is up to you whether you respond by destroying + the window. + + If you don't destroy the window, you should call wxCloseEvent::Veto to + let the calling code know that you did not destroy the window. This allows the + wxWindow::Close function + to return @true or @false depending on whether the close instruction was + honoured or not. + + @library{wxcore} + @category{events} + + @seealso + wxWindow::Close, @ref overview_windowdeletionoverview "Window deletion overview" +*/ +class wxCloseEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxCloseEvent(WXTYPE commandEventType = 0, int id = 0); + + /** + Returns @true if you can veto a system shutdown or a window close event. + Vetoing a window close event is not possible if the calling code wishes to + force the application to exit, and so this function must be called to check + this. + */ + bool CanVeto(); + + /** + Returns @true if the user is just logging off or @false if the system is + shutting down. This method can only be called for end session and query end + session events, it doesn't make sense for close window event. + */ + bool GetLoggingOff(); + + /** + Sets the 'can veto' flag. + */ + void SetCanVeto(bool canVeto); + + /** + Sets the 'force' flag. + */ + void SetForce(bool force); + + /** + Sets the 'logging off' flag. + */ + void SetLoggingOff(bool loggingOff); + + /** + Call this from your event handler to veto a system shutdown or to signal + to the calling application that a window close did not happen. + + You can only veto a shutdown if CanVeto() returns + @true. + */ + void Veto(bool veto = @true); +}; + + +/** + @class wxMenuEvent + @wxheader{event.h} + + This class is used for a variety of menu-related events. Note that + these do not include menu command events, which are + handled using wxCommandEvent objects. + + The default handler for wxEVT_MENU_HIGHLIGHT displays help + text in the first field of the status bar. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_wxcommandevent "Command events", @ref + overview_eventhandlingoverview "Event handling overview" +*/ +class wxMenuEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxMenuEvent(WXTYPE id = 0, int id = 0, wxMenu* menu = @NULL); + + /** + Returns the menu which is being opened or closed. This method should only be + used with the @c OPEN and @c CLOSE events and even for them the + returned pointer may be @NULL in some ports. + */ + wxMenu * GetMenu(); + + /** + Returns the menu identifier associated with the event. This method should be + only used with the @c HIGHLIGHT events. + */ + int GetMenuId(); + + /** + Returns @true if the menu which is being opened or closed is a popup menu, + @false if it is a normal one. + + This method should only be used with the @c OPEN and @c CLOSE events. + */ + bool IsPopup(); +}; + + +/** + @class wxEventBlocker + @wxheader{event.h} + + This class is a special event handler which allows to discard + any event (or a set of event types) directed to a specific window. + + Example: + + @code + { + // block all events directed to this window while + // we do the 1000 FuncWhichSendsEvents() calls + wxEventBlocker blocker(this); + + for ( int i = 0; i 1000; i++ ) + FuncWhichSendsEvents(i); + + } // ~wxEventBlocker called, old event handler is restored + + // the event generated by this call will be processed + FuncWhichSendsEvents(0) + @endcode + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", wxEvtHandler +*/ +class wxEventBlocker : public wxEvtHandler +{ +public: + /** + Constructs the blocker for the given window and for the given event type. + If @e type is @c wxEVT_ANY, then all events for that window are + blocked. You can call Block() after creation to + add other event types to the list of events to block. + + Note that the @e win window @b must remain alive until the + wxEventBlocker object destruction. + */ + wxEventBlocker(wxWindow* win, wxEventType type = wxEVT_ANY); + + /** + Destructor. The blocker will remove itself from the chain of event handlers for + the window provided in the constructor, thus restoring normal processing of + events. + */ + ~wxEventBlocker(); + + /** + Adds to the list of event types which should be blocked the given @e eventType. + */ + void Block(wxEventType eventType); +}; + + +/** + @class wxEvtHandler + @wxheader{event.h} + + A class that can handle events from the windowing system. + wxWindow (and therefore all window classes) are derived from + this class. + + When events are received, wxEvtHandler invokes the method listed in the + event table using itself as the object. When using multiple inheritance + it is imperative that the wxEvtHandler(-derived) class be the first + class inherited such that the "this" pointer for the overall object + will be identical to the "this" pointer for the wxEvtHandler portion. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxEvtHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxEvtHandler(); + + /** + Destructor. If the handler is part of a chain, the destructor will + unlink itself and restore the previous and next handlers so that they point to + each other. + */ + ~wxEvtHandler(); + + /** + This function posts an event to be processed later. + + @param event + Event to add to process queue. + + @remarks 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). + */ + virtual void AddPendingEvent(const wxEvent& event); + + //@{ + /** + Connects the given function dynamically with the event handler, id and event + type. This + is an alternative to the use of static event tables. See the 'event' or the old + 'dynamic' sample for usage. + + @param id + The identifier (or first of the identifier range) to be + associated with the event handler function. For the version not taking this + argument, it defaults to wxID_ANY. + + @param lastId + The second part of the identifier range to be associated with the event handler + function. + + @param eventType + The event type to be associated with this event handler. + + @param function + The event handler function. Note that this function should + be explicitly converted to the correct type which can be done using a macro + called wxFooEventHandler for the handler for any wxFooEvent. + + @param userData + Data to be associated with the event table entry. + + @param eventSink + Object whose member function should be called. If this is @NULL, + this will be used. + */ + void Connect(int id, int lastId, wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = @NULL, + wxEvtHandler* eventSink = @NULL); + void Connect(int id, wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = @NULL, + wxEvtHandler* eventSink = @NULL); + void Connect(wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = @NULL, + wxEvtHandler* eventSink = @NULL); + //@} + + //@{ + /** + Disconnects the given function dynamically from the event handler, using the + specified + parameters as search criteria and returning @true if a matching function has been + found and removed. This method can only disconnect functions which have been + added + using the Connect() method. There is no way + to disconnect functions connected using the (static) event tables. + + @param id + The identifier (or first of the identifier range) associated with the event + handler function. + + @param lastId + The second part of the identifier range associated with the event handler + function. + + @param eventType + The event type associated with this event handler. + + @param function + The event handler function. + + @param userData + Data associated with the event table entry. + + @param eventSink + Object whose member function should be called. + */ + bool Disconnect(wxEventType eventType = wxEVT_@NULL, + wxObjectEventFunction function = @NULL, + wxObject* userData = @NULL, + wxEvtHandler* eventSink = @NULL); + bool Disconnect(int id = wxID_ANY, + wxEventType eventType = wxEVT_@NULL, + wxObjectEventFunction function = @NULL, + wxObject* userData = @NULL, + wxEvtHandler* eventSink = @NULL); + bool Disconnect(int id, int lastId = wxID_ANY, + wxEventType eventType = wxEVT_@NULL, + wxObjectEventFunction function = @NULL, + wxObject* userData = @NULL, + wxEvtHandler* eventSink = @NULL); + //@} + + /** + Gets user-supplied client data. + + @remarks Normally, any extra data the programmer wishes to associate with + the object should be made available by deriving a new + class with new data members. + + @sa SetClientData() + */ + void* GetClientData(); + + /** + Get a pointer to the user-supplied client data object. + + @sa SetClientObject(), wxClientData + */ + wxClientData* GetClientObject(); + + /** + Returns @true if the event handler is enabled, @false otherwise. + + @sa SetEvtHandlerEnabled() + */ + bool GetEvtHandlerEnabled(); + + /** + Gets the pointer to the next handler in the chain. + + @sa SetNextHandler(), GetPreviousHandler(), + SetPreviousHandler(), wxWindow::PushEventHandler, + wxWindow::PopEventHandler + */ + wxEvtHandler* GetNextHandler(); + + /** + Gets the pointer to the previous handler in the chain. + + @sa SetPreviousHandler(), GetNextHandler(), + SetNextHandler(), wxWindow::PushEventHandler, + wxWindow::PopEventHandler + */ + wxEvtHandler* GetPreviousHandler(); + + /** + Processes an event, searching event tables and calling zero or more suitable + event handler function(s). + + @param event + Event to process. + + @returns @true if a suitable event handler function was found and + executed, and the function did not call wxEvent::Skip. + + @remarks 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). + + @sa SearchEventTable() + */ + virtual bool ProcessEvent(wxEvent& event); + + /** + Processes an event by calling ProcessEvent() + and handles any exceptions that occur in the process. If an exception is + thrown in event handler, wxApp::OnExceptionInMainLoop + is called. + + @param event + Event to process. + + @returns @true if the event was processed, @false if no handler was found + or an exception was thrown. + + @sa wxWindow::HandleWindowEvent + */ + bool SafelyProcessEvent(wxEvent& event); + + /** + Searches the event table, executing an event handler function if an appropriate + one + is found. + + @param table + Event table to be searched. + + @param event + Event to be matched against an event table entry. + + @returns @true if a suitable event handler function was found and + executed, and the function did not call wxEvent::Skip. + + @remarks This function looks through the object's event table and tries + to find an entry that will match the event. + + @sa ProcessEvent() + */ + virtual bool SearchEventTable(wxEventTable& table, + wxEvent& event); + + /** + Sets user-supplied client data. + + @param data + Data to be associated with the event handler. + + @remarks Normally, any extra data the programmer wishes to associate with + the object should be made available by deriving a + new class with new data members. You must not call + this method and SetClientObject on the same class - + only one of them. + + @sa GetClientData() + */ + void SetClientData(void* data); + + /** + Set the client data object. Any previous object will be deleted. + + @sa GetClientObject(), wxClientData + */ + void SetClientObject(wxClientData* data); + + /** + Enables or disables the event handler. + + @param enabled + @true if the event handler is to be enabled, @false if it is to be disabled. + + @remarks You can use this function to avoid having to remove the event + handler from the chain, for example when implementing + a dialog editor and changing from edit to test mode. + + @sa GetEvtHandlerEnabled() + */ + void SetEvtHandlerEnabled(bool enabled); + + /** + Sets the pointer to the next handler. + + @param handler + Event handler to be set as the next handler. + + @sa GetNextHandler(), SetPreviousHandler(), + GetPreviousHandler(), wxWindow::PushEventHandler, + wxWindow::PopEventHandler + */ + void SetNextHandler(wxEvtHandler* handler); + + /** + Sets the pointer to the previous handler. + + @param handler + Event handler to be set as the previous handler. + */ + void SetPreviousHandler(wxEvtHandler* handler); +}; + + +/** + @class wxIconizeEvent + @wxheader{event.h} + + An event being sent when the frame is iconized (minimized) or restored. + + Currently only wxMSW and wxGTK generate such events. + + @library{wxcore} + @category{events} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", + wxTopLevelWindow::Iconize, wxTopLevelWindow::IsIconized +*/ +class wxIconizeEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxIconizeEvent(int id = 0, bool iconized = @true); + + /** + Returns @true if the frame has been iconized, @false if it has been + restored. + */ + bool Iconized(); +}; + + +/** + @class wxMoveEvent + @wxheader{event.h} + + A move event holds information about move change events. + + @library{wxcore} + @category{events} + + @seealso + wxPoint, @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxMoveEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxMoveEvent(const wxPoint& pt, int id = 0); + + /** + Returns the position of the window generating the move change event. + */ + wxPoint GetPosition(); +}; + + +/** + @class wxEvent + @wxheader{event.h} + + An event is a structure holding information about an event passed to a + callback or member function. @b wxEvent used to be a multipurpose + event object, and is an abstract base class for other event classes (see below). + + For more information about events, see the @ref overview_eventhandlingoverview + "Event handling overview". + + @b wxPerl note: In wxPerl custom event classes should be derived from + @c Wx::PlEvent and @c Wx::PlCommandEvent. + + @library{wxbase} + @category{events} + + @seealso + wxCommandEvent, wxMouseEvent +*/ +class wxEvent : public wxObject +{ +public: + /** + Constructor. Should not need to be used directly by an application. + */ + wxEvent(int id = 0, wxEventType eventType = wxEVT_@NULL); + + /** + Returns a copy of the event. + + Any event that is posted to the wxWidgets event system for later action (via + wxEvtHandler::AddPendingEvent or + wxPostEvent) must implement this method. All wxWidgets + events fully implement this method, but any derived events implemented by the + user should also implement this method just in case they (or some event + derived from them) are ever posted. + + All wxWidgets events implement a copy constructor, so the easiest way of + implementing the Clone function is to implement a copy constructor for + a new event (call it MyEvent) and then define the Clone function like this: + */ + virtual wxEvent* Clone(); + + /** + Returns the object (usually a window) associated with the + event, if any. + */ + wxObject* GetEventObject(); + + /** + Returns the identifier of the given event type, + such as @c wxEVT_COMMAND_BUTTON_CLICKED. + */ + wxEventType GetEventType(); + + /** + Returns the identifier associated with this event, such as a button command id. + */ + int GetId(); + + /** + Returns @true if the event handler should be skipped, @false otherwise. + */ + bool GetSkipped(); + + /** + Gets the timestamp for the event. The timestamp is the time in milliseconds + since some fixed moment (not necessarily the standard Unix Epoch, so + only differences between the timestamps and not their absolute values usually + make sense). + */ + long GetTimestamp(); + + /** + Returns @true if the event is or is derived from + wxCommandEvent else it returns @false. + Note: Exists only for optimization purposes. + */ + bool IsCommandEvent(); + + /** + Sets the propagation level to the given value (for example returned from an + earlier call to wxEvent::StopPropagation). + */ + void ResumePropagation(int propagationLevel); + + /** + Sets the originating object. + */ + void SetEventObject(wxObject* object); + + /** + Sets the event type. + */ + void SetEventType(wxEventType type); + + /** + Sets the identifier associated with this event, such as a button command id. + */ + void SetId(int id); + + /** + Sets the timestamp for the event. + */ + void SetTimestamp(long timeStamp); + + /** + Test if this event should be propagated or not, i.e. if the propagation level + is currently greater than 0. + */ + bool ShouldPropagate(); + + /** + This method can be used inside an event handler to control whether further + event handlers bound to this event will be called after the current one + returns. Without Skip() (or equivalently if Skip(@false) is used), + the event will not be processed any more. If Skip(@true) is called, the event + processing system continues searching for a further handler function for this + event, even though it has been processed already in the current handler. + + In general, it is recommended to skip all non-command events to allow the + default handling to take place. The command events are, however, normally not + skipped as usually a single command such as a button click or menu item + selection must only be processed by one handler. + */ + void Skip(bool skip = @true); + + /** + Stop the event from propagating to its parent window. + + Returns the old propagation level value which may be later passed to + ResumePropagation() to allow propagating the + event again. + */ + int StopPropagation(); + + /** + int m_propagationLevel + + Indicates how many levels the event can propagate. This member is protected and + should typically only be set in the constructors of the derived classes. It + may be temporarily changed by StopPropagation() + and ResumePropagation() and tested with + ShouldPropagate(). + + The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by + default) meaning that the event shouldn't be propagated at all or to + @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be + propagated as much as necessary. + + Any positive number means that the event should be propagated but no more than + the given number of times. E.g. the propagation level may be set to 1 to + propagate the event to its parent only, but not to its grandparent. + */ +}; + + +/** + @class wxSizeEvent + @wxheader{event.h} + + A size event holds information about size change events. + + The EVT_SIZE handler function will be called when the window has been resized. + + You may wish to use this for frames to resize their child windows as + appropriate. + + Note that the size passed is of + the whole window: call wxWindow::GetClientSize for the area which may be + used by the application. + + When a window is resized, usually only a small part of the window is damaged + and you + may only need to repaint that area. However, if your drawing depends on the + size of the window, + you may need to clear the DC explicitly and repaint the whole window. In which + case, you + may need to call wxWindow::Refresh to invalidate the entire window. + + @library{wxcore} + @category{events} + + @seealso + wxSize, @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxSizeEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxSizeEvent(const wxSize& sz, int id = 0); + + /** + Returns the entire size of the window generating the size change event. + */ + wxSize GetSize(); +}; + + +/** + @class wxSetCursorEvent + @wxheader{event.h} + + A SetCursorEvent is generated when the mouse cursor is about to be set as a + result of mouse motion. This event gives the application the chance to perform + specific mouse cursor processing based on the current position of the mouse + within the window. Use wxSetCursorEvent::SetCursor to + specify the cursor you want to be displayed. + + @library{wxcore} + @category{FIXME} + + @seealso + ::wxSetCursor, wxWindow::wxSetCursor +*/ +class wxSetCursorEvent : public wxEvent +{ +public: + /** + Constructor, used by the library itself internally to initialize the event + object. + */ + wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0); + + /** + Returns a reference to the cursor specified by this event. + */ + wxCursor GetCursor(); + + /** + Returns the X coordinate of the mouse in client coordinates. + */ +#define wxCoord GetX() /* implementation is private */ + + /** + Returns the Y coordinate of the mouse in client coordinates. + */ +#define wxCoord GetY() /* implementation is private */ + + /** + Returns @true if the cursor specified by this event is a valid cursor. + + @remarks You cannot specify wxNullCursor with this event, as it is not + considered a valid cursor. + */ + bool HasCursor(); + + /** + Sets the cursor associated with this event. + */ + void SetCursor(const wxCursor& cursor); +}; diff --git a/interface/fdrepdlg.h b/interface/fdrepdlg.h new file mode 100644 index 0000000000..9e2ca39dd2 --- /dev/null +++ b/interface/fdrepdlg.h @@ -0,0 +1,160 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fdrepdlg.h +// Purpose: documentation for wxFindDialogEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFindDialogEvent + @wxheader{fdrepdlg.h} + + wxFindReplaceDialog events + + @library{wxcore} + @category{events} +*/ +class wxFindDialogEvent : public wxCommandEvent +{ +public: + /** + Constuctor used by wxWidgets only. + */ + wxFindDialogEvent(wxEventType commandType = wxEVT_@NULL, + int id = 0); + + /** + Return the pointer to the dialog which generated this event. + */ + wxFindReplaceDialog* GetDialog(); + + /** + Return the string to find (never empty). + */ + wxString GetFindString(); + + /** + Get the currently selected flags: this is the combination of @c wxFR_DOWN, + @c wxFR_WHOLEWORD and @c wxFR_MATCHCASE flags. + */ + int GetFlags(); + + /** + Return the string to replace the search string with (only for replace and + replace all events). + */ + const wxString GetReplaceString(); +}; + + +/** + @class wxFindReplaceData + @wxheader{fdrepdlg.h} + + wxFindReplaceData holds the data for + wxFindReplaceDialog. It is used to initialize + the dialog with the default values and will keep the last values from the + dialog when it is closed. It is also updated each time a + wxFindDialogEvent is generated so instead of + using the wxFindDialogEvent methods you can also directly query this object. + + Note that all @c SetXXX() methods may only be called before showing the + dialog and calling them has no effect later. + + @library{wxcore} + @category{FIXME} +*/ +class wxFindReplaceData : public wxObject +{ +public: + /** + Constuctor initializes the flags to default value (0). + */ + wxFindReplaceData(wxUint32 flags = 0); + + /** + Get the string to find. + */ + const wxString GetFindString(); + + /** + Get the combination of @c wxFindReplaceFlags values. + */ + int GetFlags(); + + /** + Get the replacement string. + */ + const wxString GetReplaceString(); + + /** + Set the string to find (used as initial value by the dialog). + */ + void SetFindString(const wxString& str); + + /** + Set the flags to use to initialize the controls of the dialog. + */ + void SetFlags(wxUint32 flags); + + /** + Set the replacement string (used as initial value by the dialog). + */ + void SetReplaceString(const wxString& str); +}; + + +/** + @class wxFindReplaceDialog + @wxheader{fdrepdlg.h} + + wxFindReplaceDialog is a standard modeless dialog which is used to allow the + user to search for some text (and possibly replace it with something else). + The actual searching is supposed to be done in the owner window which is the + parent of this dialog. Note that it means that unlike for the other standard + dialogs this one @b must have a parent window. Also note that there is no + way to use this dialog in a modal way; it is always, by design and + implementation, modeless. + + Please see the dialogs sample for an example of using it. + + @library{wxcore} + @category{cmndlg} +*/ +class wxFindReplaceDialog : public wxDialog +{ +public: + //@{ + /** + After using default constructor Create() + must be called. + + The @e parent and @e data parameters must be non-@NULL. + */ + wxFindReplaceDialog(); + wxFindReplaceDialog(wxWindow * parent, + wxFindReplaceData* data, + const wxString& title, + int style = 0); + //@} + + /** + Destructor. + */ + ~wxFindReplaceDialog(); + + /** + Creates the dialog; use wxWindow::Show to show it on screen. + + The @e parent and @e data parameters must be non-@NULL. + */ + bool Create(wxWindow * parent, wxFindReplaceData* data, + const wxString& title, int style = 0); + + /** + Get the wxFindReplaceData object used by this + dialog. + */ + const wxFindReplaceData* GetData(); +}; diff --git a/interface/ffile.h b/interface/ffile.h new file mode 100644 index 0000000000..a0d29e9e6d --- /dev/null +++ b/interface/ffile.h @@ -0,0 +1,206 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ffile.h +// Purpose: documentation for wxFFile class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFFile + @wxheader{ffile.h} + + wxFFile implements buffered file I/O. This is a very small class designed to + minimize the overhead of using it - in fact, there is hardly any overhead at + all, but using it brings you automatic error checking and hides differences + between platforms and compilers. It wraps inside it a @c FILE * handle used + by standard C IO library (also known as @c stdio). + + @library{wxbase} + @category{file} + + @seealso + wxFFile::IsOpened +*/ +class wxFFile +{ +public: + //@{ + /** + Opens a file with the given file pointer, which has already been opened. + + @param filename + The filename. + + @param mode + The mode in which to open the file using standard C strings. + Note that you should use "b" flag if you use binary files under Windows + or the results might be unexpected due to automatic newline conversion done + for the text files. + + @param fp + An existing file descriptor, such as stderr. + */ + wxFFile(); + wxFFile(const wxString& filename, const wxString& mode = "r"); + wxFFile(FILE* fp); + //@} + + /** + Destructor will close the file. + + NB: it is not virtual so you should @e not derive from wxFFile! + */ + ~wxFFile(); + + /** + Attaches an existing file pointer to the wxFFile object. + + The descriptor should be already opened and it will be closed by wxFFile + object. + */ + void Attach(FILE* fp); + + /** + Closes the file and returns @true on success. + */ + bool Close(); + + /** + Get back a file pointer from wxFFile object -- the caller is responsible for + closing the file if this + descriptor is opened. IsOpened() will return @false after call to Detach(). + */ + void Detach(); + + /** + Returns @true if the an attempt has been made to read @e past + the end of the file. + + Note that the behaviour of the file descriptor based class + wxFile is different as wxFile::Eof + will return @true here as soon as the last byte of the file has been + read. + + Also note that this method may only be called for opened files and may crash if + the file is not opened. + + @sa IsOpened() + */ +#define bool Eof() /* implementation is private */ + + /** + Returns @true if an error has occurred on this file, similar to the standard + @c ferror() function. + + Please note that this method may only be called for opened files and may crash + if the file is not opened. + + @sa IsOpened() + */ + + + /** + Flushes the file and returns @true on success. + */ + bool Flush(); + + /** + Returns the type of the file. Possible return values are: + */ + wxFileKind GetKind(); + + /** + Returns @true if the file is opened. Most of the methods of this class may + only + be used for an opened file. + */ + bool IsOpened(); + + /** + Returns the length of the file. + */ + wxFileOffset Length(); + + /** + Opens the file, returning @true if successful. + + @param filename + The filename. + + @param mode + The mode in which to open the file. + */ + bool Open(const wxString& filename, const wxString& mode = "r"); + + /** + Reads the specified number of bytes into a buffer, returning the actual number + read. + + @param buffer + A buffer to receive the data. + + @param count + The number of bytes to read. + + @returns The number of bytes read. + */ + size_t Read(void* buffer, size_t count); + + /** + ) + + Reads the entire contents of the file into a string. + + @param str + String to read data into. + + @param conv + Conversion object to use in Unicode build; by default supposes + that file contents is encoded in UTF-8. + + @returns @true if file was read successfully, @false otherwise. + */ + bool ReadAll(wxString * str); + + /** + Seeks to the specified position and returns @true on success. + + @param ofs + Offset to seek to. + + @param mode + One of wxFromStart, wxFromEnd, wxFromCurrent. + */ + bool Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart); + + /** + Moves the file pointer to the specified number of bytes before the end of the + file + and returns @true on success. + + @param ofs + Number of bytes before the end of the file. + */ + bool SeekEnd(wxFileOffset ofs = 0); + + /** + Returns the current position. + */ + wxFileOffset Tell(); + + /** + ) + + Writes the contents of the string to the file, returns @true on success. + + The second argument is only meaningful in Unicode build of wxWidgets when + @e conv is used to convert @e s to multibyte representation. + */ + bool Write(const wxString& s); + + /** + Returns the file pointer associated with the file. + */ +#define FILE * fp() /* implementation is private */ +}; diff --git a/interface/file.h b/interface/file.h new file mode 100644 index 0000000000..3b032320c1 --- /dev/null +++ b/interface/file.h @@ -0,0 +1,336 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: file.h +// Purpose: documentation for wxTempFile class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTempFile + @wxheader{file.h} + + wxTempFile provides a relatively safe way to replace the contents of the + existing file. The name is explained by the fact that it may be also used as + just a temporary file if you don't replace the old file contents. + + Usually, when a program replaces the contents of some file it first opens it for + writing, thus losing all of the old data and then starts recreating it. This + approach is not very safe because during the regeneration of the file bad things + may happen: the program may find that there is an internal error preventing it + from completing file generation, the user may interrupt it (especially if file + generation takes long time) and, finally, any other external interrupts (power + supply failure or a disk error) will leave you without either the original file + or the new one. + + wxTempFile addresses this problem by creating a temporary file which is meant to + replace the original file - but only after it is fully written. So, if the user + interrupts the program during the file generation, the old file won't be lost. + Also, if the program discovers itself that it doesn't want to replace the old + file there is no problem - in fact, wxTempFile will @b not replace the old + file by default, you should explicitly call wxTempFile::Commit + to do it. Calling wxTempFile::Discard explicitly discards any + modifications: it closes and deletes the temporary file and leaves the original + file unchanged. If you don't call neither of Commit() and Discard(), the + destructor will call Discard() automatically. + + To summarize: if you want to replace another file, create an instance of + wxTempFile passing the name of the file to be replaced to the constructor (you + may also use default constructor and pass the file name to + wxTempFile::Open). Then you can wxTempFile::write + to wxTempFile using wxFile-like functions and later call + Commit() to replace the old file (and close this one) or call Discard() to + cancel + the modifications. + + @library{wxbase} + @category{file} +*/ +class wxTempFile +{ +public: + /** + Associates wxTempFile with the file to be replaced and opens it. You should use + IsOpened() to verify if the constructor succeeded. + */ + wxTempFile(const wxString& strName); + + /** + Destructor calls Discard() if temporary file + is still opened. + */ + ~wxTempFile(); + + /** + Validate changes: deletes the old file of name m_strName and renames the new + file to the old name. Returns @true if both actions succeeded. If @false is + returned it may unfortunately mean two quite different things: either that + either the old file couldn't be deleted or that the new file couldn't be renamed + to the old name. + */ + bool Commit(); + + /** + Discard changes: the old file contents is not changed, temporary file is + deleted. + */ + void Discard(); + + /** + Returns @true if the file was successfully opened. + */ + bool IsOpened(); + + /** + Returns the length of the file. + */ + wxFileOffset Length(); + + /** + Open the temporary file, returns @true on success, @false if an error + occurred. + + @e strName is the name of file to be replaced. The temporary file is always + created in the directory where @e strName is. In particular, if + @e strName doesn't include the path, it is created in the current directory + and the program should have write access to it for the function to succeed. + */ + bool Open(const wxString& strName); + + /** + Seeks to the specified position. + */ + wxFileOffset Seek(wxFileOffset ofs, + wxSeekMode mode = wxFromStart); + + /** + Returns the current position or wxInvalidOffset if file is not opened or if + another + error occurred. + */ + wxFileOffset Tell(); + + /** + Write to the file, return @true on success, @false on failure. + + The second argument is only meaningful in Unicode build of wxWidgets when + @e conv is used to convert @e str to multibyte representation. + */ + bool Write(const wxString& str, + const wxMBConv& conv = wxConvUTF8); +}; + + +/** + @class wxFile + @wxheader{file.h} + + A wxFile performs raw file I/O. This is a very small class designed to + minimize the overhead of using it - in fact, there is hardly any overhead at + all, but using it brings you automatic error checking and hides differences + between platforms and compilers. wxFile also automatically closes the file in + its destructor making it unnecessary to worry about forgetting to do it. + wxFile is a wrapper around @c file descriptor. - see also + wxFFile for a wrapper around @c FILE structure. + + @c wxFileOffset is used by the wxFile functions which require offsets as + parameter or return them. If the platform supports it, wxFileOffset is a typedef + for a native 64 bit integer, otherwise a 32 bit integer is used for + wxFileOffset. + + @library{wxbase} + @category{file} +*/ +class wxFile +{ +public: + //@{ + /** + Associates the file with the given file descriptor, which has already been + opened. + + @param filename + The filename. + + @param mode + The mode in which to open the file. May be one of read(), write() and + wxFile::read_write. + + @param fd + An existing file descriptor (see Attach() for the list of predefined + descriptors) + */ + wxFile(); + wxFile(const wxString& filename, + wxFile::OpenMode mode = wxFile::read); + wxFile(int fd); + //@} + + /** + Destructor will close the file. + + @b NB: it is not virtual so you should not use wxFile polymorphically. + */ + ~wxFile(); + + /** + This function verifies if we may access the given file in specified mode. Only + values of read() or write() really make sense here. + */ + static bool Access(const wxString& name, OpenMode mode); + + /** + Attaches an existing file descriptor to the wxFile object. Example of predefined + file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr + (and + have symbolic names of @b wxFile::fd_stdin, @b wxFile::fd_stdout and @b + wxFile::fd_stderr). + + The descriptor should be already opened and it will be closed by wxFile + object. + */ + void Attach(int fd); + + /** + Closes the file. + */ + void Close(); + + /** + Creates a file for writing. If the file already exists, setting @b overwrite to + @true + will ensure it is overwritten. + */ + bool Create(const wxString& filename, bool overwrite = @false, + int access = wxS_DEFAULT); + + /** + Get back a file descriptor from wxFile object - the caller is responsible for + closing the file if this + descriptor is opened. IsOpened() will return @false after call to Detach(). + */ + void Detach(); + + /** + Returns @true if the end of the file has been reached. + + Note that the behaviour of the file pointer based class + wxFFile is different as wxFFile::Eof + will return @true here only if an attempt has been made to read + @e past the last byte of the file, while wxFile::Eof() will return @true + even before such attempt is made if the file pointer is at the last position + in the file. + + Note also that this function doesn't work on unseekable file descriptors + (examples include pipes, terminals and sockets under Unix) and an attempt to + use it will result in an error message in such case. So, to read the entire + file into memory, you should write a loop which uses + Read() repeatedly and tests its return condition instead + of using Eof() as this will not work for special files under Unix. + */ +#define bool Eof() /* implementation is private */ + + /** + Returns @true if the given name specifies an existing regular file (not a + directory or a link) + */ + static bool Exists(const wxString& filename); + + /** + Flushes the file descriptor. + + Note that Flush() is not implemented on some Windows compilers + due to a missing fsync function, which reduces the usefulness of this function + (it can still be called but it will do nothing on unsupported compilers). + */ + bool Flush(); + + /** + Returns the type of the file. Possible return values are: + */ + wxFileKind GetKind(); + + /** + Returns @true if the file has been opened. + */ + bool IsOpened(); + + /** + Returns the length of the file. + */ + wxFileOffset Length(); + + /** + Opens the file, returning @true if successful. + + @param filename + The filename. + + @param mode + The mode in which to open the file. May be one of read(), write() and + wxFile::read_write. + */ + bool Open(const wxString& filename, + wxFile::OpenMode mode = wxFile::read); + + //@{ + /** + if there was an error. + */ + size_t Read(void* buffer, size_t count); + Parameters Return value +The number of bytes read, or the symbol wxInvalidOffset(); + //@} + + /** + Seeks to the specified position. + + @param ofs + Offset to seek to. + + @param mode + One of wxFromStart, wxFromEnd, wxFromCurrent. + + @returns The actual offset position achieved, or wxInvalidOffset on + failure. + */ + wxFileOffset Seek(wxFileOffset ofs, + wxSeekMode mode = wxFromStart); + + /** + Moves the file pointer to the specified number of bytes relative to the end of + the file. For example, @c SeekEnd(-5) would position the pointer 5 + bytes before the end. + + @param ofs + Number of bytes before the end of the file. + + @returns The actual offset position achieved, or wxInvalidOffset on + failure. + */ + wxFileOffset SeekEnd(wxFileOffset ofs = 0); + + /** + Returns the current position or wxInvalidOffset if file is not opened or if + another + error occurred. + */ + wxFileOffset Tell(); + + /** + Writes the contents of the string to the file, returns @true on success. + + The second argument is only meaningful in Unicode build of wxWidgets when + @e conv is used to convert @e s to multibyte representation. + + Note that this method only works with @c NUL-terminated strings, if you want + to write data with embedded @c NULs to the file you should use the other + @ref write() "Write() overload". + */ + bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8); + + /** + Returns the file descriptor associated with the file. + */ +#define int fd() /* implementation is private */ +}; diff --git a/interface/fileconf.h b/interface/fileconf.h new file mode 100644 index 0000000000..84434c6317 --- /dev/null +++ b/interface/fileconf.h @@ -0,0 +1,92 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fileconf.h +// Purpose: documentation for wxFileConfig class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileConfig + @wxheader{fileconf.h} + + wxFileConfig implements wxConfigBase interface for + storing and retrieving configuration information using plain text files. The + files have a simple format reminiscent of Windows INI files with lines of the + form @c key = value defining the keys and lines of special form + @c [group] indicating the start of each group. + + This class is used by default for wxConfig on Unix platforms but may also be + used explicitly if you want to use files and not the registry even under + Windows. + + @library{wxbase} + @category{FIXME} + + @seealso + wxFileConfig::Save +*/ +class wxFileConfig : public wxConfigBase +{ +public: + /** + ) + + Read the config data from the specified stream instead of the associated file, + as usual. + + @sa Save() + */ + wxFileConfig(wxInputStream& is); + + /** + Return the full path to the file which would be used by wxFileConfig as global, + system-wide, file if it were constructed with @e basename as "global + filename'' parameter in the constructor. Notice that this function cannot be + used if @e basename is already a full path name. + */ + static wxFileName GetGlobalFile(const wxString& basename); + + /** + Return the full path to the file which would be used by wxFileConfig as local, + user-specific, file if it were constructed with @e basename as "local + filename'' parameter in the constructor. + + @e style has the same meaning as in @ref wxConfigBase::ctor constructor + and can contain any combination of styles but only wxCONFIG_USE_SUBDIR bit is + examined by this function. + + Notice that this function cannot be used if @e basename is already a full + path name. + */ + static wxFileName GetLocalFile(const wxString& basename, + int style = 0); + + /** + ) + + Saves all config data to the given stream, returns @true if data was saved + successfully or @false on error. + + Note the interaction of this function with the internal "dirty flag'': the + data is saved unconditionally, i.e. even if the object is not dirty. However + after saving it successfully, the dirty flag is reset so no changes will be + written back to the file this object is associated with until you change its + contents again. + + @sa wxConfigBase::Flush + */ + bool Save(wxOutputStream& os); + + /** + Allows to set the mode to be used for the config file creation. For example, to + create a config file which is not readable by other users (useful if it stores + some sensitive information, such as passwords), you could use + @c SetUmask(0077). + + This function doesn't do anything on non-Unix platforms. + + @sa wxCHANGE_UMASK + */ + void SetUmask(int mode); +}; diff --git a/interface/filectrl.h b/interface/filectrl.h new file mode 100644 index 0000000000..1f5e5ffc2d --- /dev/null +++ b/interface/filectrl.h @@ -0,0 +1,223 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filectrl.h +// Purpose: documentation for wxFileCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileCtrl + @wxheader{filectrl.h} + + This control allows the user to select a file. two implemetations exist, one + for Gtk and another generic one for anything other than Gtk. + It is only available if @c wxUSE_FILECTRL is set to 1. + + @beginStyleTable + @style{wxFC_DEFAULT_STYLE}: + The default style: wxFC_OPEN + @style{wxFC_OPEN}: + Creates an file control suitable for opening files. Cannot be + combined with wxFC_SAVE. + @style{wxFC_SAVE}: + Creates an file control suitable for saving files. Cannot be + combined with wxFC_OPEN. + @style{wxFC_MULTIPLE}: + For open control only, Allows selecting multiple files. Cannot be + combined with wxFC_SAVE + @style{wxFC_NOSHOWHIDDEN}: + Hides the "Show Hidden Files" checkbox (Generic only) + @endStyleTable + + @library{wxbase} + @category{FIXME} + + @seealso + wxGenericDirCtrl +*/ +class wxFileCtrl : public wxWindow +{ +public: + //@{ + /** + @param parent + Parent window, must not be non-@NULL. + + @param id + The identifier for the control. + + @param defaultDirectory + The initial directory shown in the control. Must be + a valid path to a directory or the empty string. + In case it is the empty string, the current working directory is used. + + @param defaultFilename + The default filename, or the empty string. + + @param wildcard + A wildcard specifying which files can be selected, + such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". + + @param style + The window style, see wxFC_* flags. + + @param pos + Initial position. + + @param size + Initial size. + + @param name + Control name. + + @returns @true if the control was successfully created or @false if + creation failed. + */ + wxFileCtrl(); + wxFileCtrl(wxWindow * parent, wxWindowID id, + const wxString& defaultDirectory = wxEmptyString, + const wxString& defaultFilename = wxEmptyString, + const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr, + long style = wxFC_DEFAULT_STYLE, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + const wxString& name = "filectrl"); + //@} + + /** + Create function for two-step construction. See wxFileCtrl() for details. + */ + bool Create(wxWindow * parent, wxWindowID id, + const wxString& defaultDirectory = wxEmptyString, + const wxString& defaultFilename = wxEmptyString, + const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr, + long style = wxFC_DEFAULT_STYLE, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + const wxString& name = "filectrl"); + + /** + Returns the current directory of the file control (i.e. the directory shown by + it). + */ + wxString GetDirectory(); + + /** + Returns the currently selected filename. + For the controls having the @c wxFC_MULTIPLE style, use GetFilenames() + instead + */ + wxString GetFilename(); + + /** + Fills the array @e filenames with the filenames only of selected items. This + function should only be used with the controls having the @c wxFC_MULTIPLE + style, + use GetFilename() for the others. + + @remarks filenames is emptied first. + */ + void GetFilenames(wxArrayString& filenames); + + /** + Returns the zero-based index of the currently selected filter. + */ + int GetFilterIndex(); + + /** + Returns the full path (directory and filename) of the currently selected file. + For the controls having the @c wxFC_MULTIPLE style, use GetPaths() + instead + */ + wxString GetPath(); + + /** + Fills the array @e paths with the full paths of the files chosen. This + function should be used with the controls having the @c wxFC_MULTIPLE style, + use GetPath() otherwise. + + @remarks paths is emptied first. + */ + void GetPaths(wxArrayString& paths); + + /** + Returns the current wildcard. + */ + wxString GetWildcard(); + + /** + Sets(changes) the current directory displayed in the control. + + @returns Returns @true on success, @false otherwise. + */ + bool SetDirectory(const wxString& directory); + + /** + Selects a certain file. + + @returns Returns @true on success, @false otherwise + */ + bool SetFilename(const wxString& filename); + + /** + Sets the current filter index, starting from zero. + */ + void SetFilterIndex(int filterIndex); + + /** + Sets the wildcard, which can contain multiple file types, for example: + + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" + */ + void SetWildcard(const wxString& wildCard); + + /** + Sets whether hidden files and folders are shown or not. + */ + void ShowHidden(const bool show); +}; + + +/** + @class wxFileCtrlEvent + @wxheader{filectrl.h} + + A file control event holds information about events associated with + wxFileCtrl objects. + + @library{wxbase} + @category{FIXME} +*/ +class wxFileCtrlEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxFileCtrlEvent(wxEventType type, wxObject evtObject, int id); + + /** + Returns the current directory. + In case of a @b EVT_FILECTRL_FOLDERCHANGED, this method returns the new + directory. + */ + wxString GetDirectory(); + + /** + Returns the file selected(assuming it is only one file). + */ + wxString GetFile(); + + /** + Returns the files selected. + In case of a @b EVT_FILECTRL_SELECTIONCHANGED, this method returns the + files selected after the event. + */ + wxArrayString GetFiles(); + + /** + Sets the files changed by this event. + */ + wxFileCtrlEvent::SetFiles(const wxArrayString files); +}; diff --git a/interface/filedlg.h b/interface/filedlg.h new file mode 100644 index 0000000000..a4f143660d --- /dev/null +++ b/interface/filedlg.h @@ -0,0 +1,265 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filedlg.h +// Purpose: documentation for wxFileDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileDialog + @wxheader{filedlg.h} + + This class represents the file chooser dialog. + + @beginStyleTable + @style{wxFD_DEFAULT_STYLE}: + Equivalent to wxFD_OPEN. + @style{wxFD_OPEN}: + This is an open dialog; usually this means that the default + button's label of the dialog is "Open". Cannot be combined with + wxFD_SAVE. + @style{wxFD_SAVE}: + This is a save dialog; usually this means that the default button's + label of the dialog is "Save". Cannot be combined with wxFD_OPEN. + @style{wxFD_OVERWRITE_PROMPT}: + For save dialog only: prompt for a confirmation if a file will be + overwritten. + @style{wxFD_FILE_MUST_EXIST}: + For open dialog only: the user may only select files that actually + exist. + @style{wxFD_MULTIPLE}: + For open dialog only: allows selecting multiple files. + @style{wxFD_CHANGE_DIR}: + Change the current working directory to the directory where the + file(s) chosen by the user are. + @style{wxFD_PREVIEW}: + Show the preview of the selected files (currently only supported by + wxGTK using GTK+ 2.4 or later). + @endStyleTable + + @library{wxcore} + @category{cmndlg} + + @seealso + @ref overview_wxfiledialogoverview "wxFileDialog overview", wxFileSelector +*/ +class wxFileDialog : public wxDialog +{ +public: + /** + Constructor. Use ShowModal() to show the dialog. + + @param parent + Parent window. + + @param message + Message to show on the dialog. + + @param defaultDir + The default directory, or the empty string. + + @param defaultFile + The default filename, or the empty string. + + @param wildcard + A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". + + Note that the native Motif dialog has some limitations with respect to + wildcards; see the Remarks section above. + + @param style + A dialog style. See wxFD_* styles for more info. + + @param pos + Dialog position. Not implemented. + + @param size + Dialog size. Not implemented. + + @param name + Dialog name. Not implemented. + */ + wxFileDialog(wxWindow* parent, + const wxString& message = "Choose a file", + const wxString& defaultDir = "", + const wxString& defaultFile = "", + const wxString& wildcard = ".", + long style = wxFD_DEFAULT_STYLE, + const wxPoint& pos = wxDefaultPosition, + const wxSize& sz = wxDefaultSize, + const wxString& name = "filedlg"); + + /** + Destructor. + */ + ~wxFileDialog(); + + /** + Returns the default directory. + */ + wxString GetDirectory(); + + /** + If functions + SetExtraControlCreator() + and ShowModal() were called, + returns the extra window. Otherwise returns @NULL. + */ + wxWindow* GetExtraControl(); + + /** + Returns the default filename. + */ + wxString GetFilename(); + + /** + Fills the array @e filenames with the names of the files chosen. This + function should only be used with the dialogs which have @c wxFD_MULTIPLE style, + use GetFilename() for the others. + + Note that under Windows, if the user selects shortcuts, the filenames + include paths, since the application cannot determine the full path + of each referenced file by appending the directory containing the shortcuts + to the filename. + */ + void GetFilenames(wxArrayString& filenames); + + /** + Returns the index into the list of filters supplied, optionally, in the + wildcard parameter. + Before the dialog is shown, this is the index which will be used when the + dialog is first displayed. + After the dialog is shown, this is the index selected by the user. + */ + int GetFilterIndex(); + + /** + Returns the message that will be displayed on the dialog. + */ + wxString GetMessage(); + + /** + Returns the full path (directory and filename) of the selected file. + */ + wxString GetPath(); + + /** + Fills the array @e paths with the full paths of the files chosen. This + function should only be used with the dialogs which have @c wxFD_MULTIPLE style, + use GetPath() for the others. + */ + void GetPaths(wxArrayString& paths); + + /** + Returns the file dialog wildcard. + */ + wxString GetWildcard(); + + /** + Sets the default directory. + */ + void SetDirectory(const wxString& directory); + + /** + Customize file dialog by adding extra window, which is typically placed + below the list of files and above the buttons. + + SetExtraControlCreator can be called only once, before calling + ShowModal(). + The @c creator function should take pointer to parent window (file dialog) + and should return a window allocated with operator new. + + Supported platforms: wxGTK, wxUniv. + */ + bool SetExtraControlCreator(t_extraControlCreator creator); + + /** + Sets the default filename. + */ + void SetFilename(const wxString& setfilename); + + /** + Sets the default filter index, starting from zero. + */ + void SetFilterIndex(int filterIndex); + + /** + Sets the message that will be displayed on the dialog. + */ + void SetMessage(const wxString& message); + + /** + Sets the path (the combined directory and filename that will be returned when + the dialog is dismissed). + */ + void SetPath(const wxString& path); + + /** + Sets the wildcard, which can contain multiple file types, for example: + + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" + + Note that the native Motif dialog has some limitations with respect to + wildcards; see the Remarks section above. + */ + void SetWildcard(const wxString& wildCard); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL + otherwise. + */ + int ShowModal(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Pops up a file selector box. In Windows, this is the common file selector + dialog. In X, this is a file selector box with the same functionality. + The path and filename are distinct elements of a full file pathname. + If path is empty, the current directory will be used. If filename is empty, + no default filename will be supplied. The wildcard determines what files + are displayed in the file selector, and file extension supplies a type + extension for the required filename. Flags may be a combination of wxFD_OPEN, + wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST. Note that + wxFD_MULTIPLE + can only be used with wxFileDialog and not here as this + function only returns a single file name. + + Both the Unix and Windows versions implement a wildcard filter. Typing a + filename containing wildcards (*, ?) in the filename text item, and + clicking on Ok, will result in only those files matching the pattern being + displayed. + + The wildcard may be a specification for multiple types of file + with a description for each, such as: + @code + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" + @endcode + + The application must check for an empty return value (the user pressed + Cancel). For example: + @code + wxString filename = wxFileSelector("Choose a file to open"); + if ( !filename.empty() ) + { + // work with the file + ... + } + //else: cancelled by user + @endcode +*/ +wxString wxFileSelector(const wxString& message, + const wxString& default_path = "", + const wxString& default_filename = "", + const wxString& default_extension = "", + const wxString& wildcard = ".", + int flags = 0, + wxWindow * parent = @NULL, + int x = -1, + int y = -1); + diff --git a/interface/filefn.h b/interface/filefn.h new file mode 100644 index 0000000000..1fed16f524 --- /dev/null +++ b/interface/filefn.h @@ -0,0 +1,371 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filefn.h +// Purpose: documentation for wxPathList class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPathList + @wxheader{filefn.h} + + The path list is a convenient way of storing a number of directories, and + when presented with a filename without a directory, searching for an existing + file + in those directories. + + Be sure to look also at wxStandardPaths if you only + want to search files in some standard paths. + + @library{wxbase} + @category{file} + + @seealso + wxArrayString, wxStandardPaths, wxFileName +*/ +class wxPathList : public wxArrayString +{ +public: + //@{ + /** + Constructs the object calling the Add() function. + */ + wxPathList(); + wxPathList(const wxArrayString& arr); + //@} + + //@{ + /** + The first form adds the given directory to the path list, if the path is not + already in the list. + If the path cannot be normalized for some reason, it returns @false. + + The second form just calls the first form on all elements of the given array. + + The @e path is always considered a directory but no existence checks will be + done on it + (because if it doesn't exist, it could be created later and thus result a valid + path when + FindValidPath() is called). + + @b Note: if the given path is relative, it won't be made absolute before adding + it + (this is why FindValidPath() may return relative paths). + */ + bool Add(const wxString& path); + void Add(const wxArrayString& arr); + //@} + + /** + Finds the value of the given environment variable, and adds all paths + to the path list. Useful for finding files in the @c PATH variable, for + example. + */ + void AddEnvList(const wxString& env_variable); + + /** + Given a full filename (with path), calls Add() with the path + of the file. + */ + bool EnsureFileAccessible(const wxString& filename); + + /** + Like FindValidPath() but this function always + returns an absolute path (eventually prepending the current working directory + to the value returned wxPathList::FindValidPath) or an + empty string. + */ + wxString FindAbsoluteValidPath(const wxString& file); + + /** + Searches the given file in all paths stored in this class. + The first path which concatenated to the given string points to an existing + file (see @ref wxFile::exists wxFileExists) is returned. + + If the file wasn't found in any of the stored paths, an empty string is + returned. + + The given string must be a file name, eventually with a path prefix (if the path + prefix is absolute, only its name will be searched); i.e. it must not end with + a directory separator (see wxFileName::GetPathSeparator) + otherwise an assertion will fail. + + The returned path may be relative to the current working directory. + Note in fact that wxPathList can be used to store both relative and absolute + paths so that + if you Added() relative paths, then the current working directory + (see wxGetCwd and wxSetWorkingDirectory) + may affect the value returned by this function! + */ + wxString FindValidPath(const wxString& file); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + This function returns the total number of bytes and number of free bytes on + the disk containing the directory @e path (it should exist). Both + @e total and @e free parameters may be @NULL if the corresponding + information is not needed. +*/ +bool wxGetDiskSpace(const wxString& path, + wxLongLong total = @NULL, + wxLongLong free = @NULL); + +/** + Returns the Windows directory under Windows; on other platforms returns the + empty string. +*/ +wxString wxGetOSDirectory(); + +/** + Parses the @e wildCard, returning the number of filters. + Returns 0 if none or if there's a problem. + The arrays will contain an equal number of items found before the error. + On platforms where native dialogs handle only one filter per entry, + entries in arrays are automatically adjusted. + @e wildCard is in the form: + + @code + "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png" + @endcode +*/ +int wxParseCommonDialogsFilter(const wxString& wildCard, + wxArrayString& descriptions, + wxArrayString& filters); + +/** + This function is deprecated, use wxFileName instead. + + Converts a Unix to a DOS filename by replacing forward + slashes with backslashes. +*/ +void wxUnix2DosFilename(wxChar * s); + +/** + Returns @true if @e dirname exists and is a directory. +*/ +bool wxDirExists(const wxString& dirname); + +/** + @b NB: This function is obsolete, please use + wxFileName::SplitPath instead. + + This function splits a full file name into components: the path (including + possible disk/drive + specification under Windows), the base name and the extension. Any of the + output parameters + (@e path, @e name or @e ext) may be @NULL if you are not interested in the value + of + a particular component. + + wxSplitPath() will correctly handle filenames with both DOS and Unix path + separators under + Windows, however it will not consider backslashes as path separators under Unix + (where backslash + is a valid character in a filename). + + On entry, @e fullname should be non-@NULL (it may be empty though). + + On return, @e path contains the file path (without the trailing separator), @e + name + contains the file name and @e 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). +*/ +void wxSplitPath(const wxString& fullname, wxString * path, + wxString * name, + wxString * ext); + +/** + Under Unix this macro changes the current process umask to the given value, + unless it is equal to -1 in which case nothing is done, and restores it to + the original value on scope exit. It works by declaring a variable which sets + umask to @e mask in its constructor and restores it in its destructor. + + Under other platforms this macro expands to nothing. +*/ +#define wxCHANGE_UMASK(int mask) /* implementation is private */ + +/** + Returns time of last modification of given file. + + The function returns @c (time_t)-1 if an error occurred (e.g. file not + found). +*/ +time_t wxFileModificationTime(const wxString& filename); + +//@{ +/** + @b NB: This function is obsolete, please use + wxFileName::SplitPath instead. + + Returns the filename for a full path. The second form returns a pointer to + temporary storage that should not be deallocated. +*/ +wxString wxFileNameFromPath(const wxString& path); + char * wxFileNameFromPath(char * path); +//@} + +/** + Renames @e file1 to @e file2, returning @true if successful. + + If @e overwrite parameter is @true (default), the destination file is + overwritten if it exists, but if @e overwrite is @false, the functions fails + in this case. +*/ +bool wxRenameFile(const wxString& file1, const wxString& file2, + bool overwrite = @true); + +/** + Copies @e file1 to @e file2, returning @true if successful. If + @e overwrite parameter is @true (default), the destination file is overwritten + if it exists, but if @e overwrite is @false, the functions fails in this + case. + + This function supports resources forks under Mac OS. +*/ +bool wxCopyFile(const wxString& file1, const wxString& file2, + bool overwrite = @true); + +/** + Returns @true if the file exists and is a plain file. +*/ +bool wxFileExists(const wxString& filename); + +/** + Returns @true if the @e pattern matches the @e text; if @e dot_special is @true, + filenames beginning with a dot are not matched + with wildcard characters. See wxIsWild. +*/ +bool wxMatchWild(const wxString& pattern, const wxString& text, + bool dot_special); + +/** + @b NB: This function is deprecated: use wxGetCwd instead. + + Copies the current working directory into the buffer if supplied, or + copies the working directory into new storage (which you must delete + yourself) if the buffer is @NULL. + + @e sz is the size of the buffer if supplied. +*/ +wxString wxGetWorkingDirectory(char * buf=@NULL, int sz=1000); + +/** + Returns the directory part of the filename. +*/ +wxString wxPathOnly(const wxString& path); + +/** + Returns @true if the pattern contains wildcards. See wxMatchWild. +*/ +bool wxIsWild(const wxString& pattern); + +/** + Returns a string containing the current (or working) directory. +*/ +wxString wxGetCwd(); + +/** + Converts a DOS to a Unix filename by replacing backslashes with forward + slashes. +*/ +void wxDos2UnixFilename(wxChar * s); + +/** + Concatenates @e file1 and @e file2 to @e file3, returning + @true if successful. +*/ +bool wxConcatFiles(const wxString& file1, const wxString& file2, + const wxString& file3); + +/** + Removes @e file, returning @true if successful. +*/ +bool wxRemoveFile(const wxString& file); + +/** + Sets the current working directory, returning @true if the operation succeeded. + Under MS Windows, the current drive is also changed if @e dir contains a drive + specification. +*/ +bool wxSetWorkingDirectory(const wxString& dir); + +/** + Makes the directory @e dir, returning @true if successful. + + @e perm is the access mask for the directory for the systems on which it is + supported (Unix) and doesn't have any effect on the other ones. +*/ +bool wxMkdir(const wxString& dir, int perm = 0777); + +/** + Returns @true if the argument is an absolute filename, i.e. with a slash + or drive name at the beginning. +*/ +bool wxIsAbsolutePath(const wxString& filename); + +/** + Returns the next file that matches the path passed to wxFindFirstFile. + + See wxFindFirstFile for an example. +*/ +wxString wxFindNextFile(); + +/** + This function does directory searching; returns the first file + that matches the path @e spec, or the empty string. Use wxFindNextFile to + get the next matching file. Neither will report the current directory "." or the + parent directory "..". +*/ +wxString wxFindFirstFile(const wxString& spec, int flags = 0); + +//@{ +/** + Returns the type of an open file. Possible return values are: + @code + 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 + }; + @endcode +*/ +wxFileKind wxGetFileKind(int fd); + wxFileKind wxGetFileKind(FILE * fp); +//@} + +//@{ +/** + @b NB: These functions are obsolete, please use + wxFileName::CreateTempFileName + instead. +*/ +char * wxGetTempFileName(const wxString& prefix, char * buf=@NULL); + bool wxGetTempFileName(const wxString& prefix, wxString& buf); +//@} + +/** + Removes the directory @e dir, returning @true if successful. Does not work under + VMS. + + The @e flags parameter is reserved for future use. + + Please notice that there is also a wxRmDir() function which simply wraps the + standard POSIX rmdir() function and so return an integer error code instead of + a boolean value (but otherwise is currently identical to wxRmdir), don't + confuse these two functions. +*/ +bool wxRmdir(const wxString& dir, int flags=0); + diff --git a/interface/filename.h b/interface/filename.h new file mode 100644 index 0000000000..225fb4a5e7 --- /dev/null +++ b/interface/filename.h @@ -0,0 +1,987 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filename.h +// Purpose: documentation for wxFileName class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileName + @wxheader{filename.h} + + wxFileName encapsulates a file name. This class serves two purposes: first, it + provides the functions to split the file names into components and to recombine + these components in the full file name which can then be passed to the OS file + functions (and @ref overview_filefunctions "wxWidgets functions" wrapping them). + Second, it includes the functions for working with the files itself. Note that + to change the file data you should use wxFile class instead. + wxFileName provides functions for working with the file attributes. + + When working with directory names (i.e. without filename and extension) + make sure not to misuse the file name part of this class with the last + directory. Instead initialize the wxFileName instance like this: + + @code + wxFileName dirname( "C:\mydir", "" ); + MyMethod( dirname.GetPath() ); + @endcode + + The same can be done using the static method wxFileName::DirName: + + @code + wxFileName dirname = wxFileName::DirName( "C:\mydir" ); + MyMethod( dirname.GetPath() ); + @endcode + + Accordingly, methods dealing with directories or directory names + like wxFileName::IsDirReadable use + wxFileName::GetPath whereas methods dealing + with file names like wxFileName::IsFileReadable + use wxFileName::GetFullPath. + + If it is not known wether a string contains a directory name or + a complete file name (such as when interpreting user input) you need to use + the static function wxFileName::DirExists + (or its identical variants wxDir::Exists and + wxDirExists) and construct the wxFileName + instance accordingly. This will only work if the directory actually exists, + of course: + + @code + wxString user_input; + // get input from user + + wxFileName fname; + if (wxDirExists(user_input)) + fname.AssignDir( user_input ); + else + fname.Assign( user_input ); + @endcode + + @library{wxbase} + @category{file} + + @seealso + wxFileName::GetCwd +*/ +class wxFileName +{ +public: + //@{ + /** + Constructor from a volume name, a directory name, base file name and extension. + */ + wxFileName(); + wxFileName(const wxFileName& filename); + wxFileName(const wxString& fullpath, + wxPathFormat format = wxPATH_NATIVE); + wxFileName(const wxString& path, const wxString& name, + wxPathFormat format = wxPATH_NATIVE); + wxFileName(const wxString& path, const wxString& name, + const wxString& ext, + wxPathFormat format = wxPATH_NATIVE); + wxFileName(const wxString& volume, const wxString& path, + const wxString& name, + const wxString& ext, + wxPathFormat format = wxPATH_NATIVE); + //@} + + /** + Appends a directory component to the path. This component should contain a + single directory name level, i.e. not contain any path or volume separators nor + should it be empty, otherwise the function does nothing (and generates an + assert failure in debug build). + */ + void AppendDir(const wxString& dir); + + //@{ + /** + Creates the file name from various combinations of data. + */ + void Assign(const wxFileName& filepath); + void Assign(const wxString& fullpath, + wxPathFormat format = wxPATH_NATIVE); + void Assign(const wxString& volume, const wxString& path, + const wxString& name, + const wxString& ext, + bool hasExt, + wxPathFormat format = wxPATH_NATIVE); + void Assign(const wxString& volume, const wxString& path, + const wxString& name, + const wxString& ext, + wxPathFormat format = wxPATH_NATIVE); + void Assign(const wxString& path, const wxString& name, + wxPathFormat format = wxPATH_NATIVE); + void Assign(const wxString& path, const wxString& name, + const wxString& ext, + wxPathFormat format = wxPATH_NATIVE); + //@} + + /** + Makes this object refer to the current working directory on the specified + volume (or current volume if @e volume is empty). + + @sa GetCwd() + */ + static void AssignCwd(const wxString& volume = wxEmptyString); + + /** + Sets this file name object to the given directory name. The name and extension + will be empty. + */ + void AssignDir(const wxString& dir, + wxPathFormat format = wxPATH_NATIVE); + + /** + Sets this file name object to the home directory. + */ + void AssignHomeDir(); + + /** + The function calls CreateTempFileName() to + create a temporary file and sets this object to the name of the file. If a + temporary file couldn't be created, the object is put into the + @ref isok() invalid state. + */ + void AssignTempFileName(const wxString& prefix, + wxFile * fileTemp = @NULL); + + /** + Reset all components to default, uninitialized state. + */ + void Clear(); + + /** + Removes the extension from the file name resulting in a + file name with no trailing dot. + + @sa SetExt(), SetEmptyExt() + */ + void SetClearExt(); + + /** + Returns a temporary file name starting with the given @e prefix. If + the @e 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 + @e 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 @e fileTemp is @NULL, the file is only created, but not opened. + + Under Unix, the temporary file will have read and write permissions for the + owner only to minimize the security problems. + + @param prefix + Prefix to use for the temporary file name construction + + @param fileTemp + The file to open or @NULL to just get the name + + @returns The full temporary file name or an empty string on error. + */ + static wxString CreateTempFileName(const wxString& prefix, + wxFile * fileTemp = @NULL); + + //@{ + /** + Returns @true if the directory with this name exists. + */ + bool DirExists(); + static bool DirExists(const wxString& dir); + //@} + + /** + Returns the object corresponding to the directory with the given name. + The @e dir parameter may have trailing path separator or not. + */ + static wxFileName DirName(const wxString& dir, + wxPathFormat format = wxPATH_NATIVE); + + /** + These functions allow to examine and modify the individual directories of the + path: + + AppendDir() + + InsertDir() + + GetDirCount() + PrependDir() + + RemoveDir() + + RemoveLastDir() + + To change the components of the file name individually you can use the + following functions: + + GetExt() + + GetName() + + GetVolume() + + HasExt() + + HasName() + + HasVolume() + + SetExt() + + ClearExt() + + SetEmptyExt() + + SetName() + + SetVolume() + */ + + + /** + You can initialize a wxFileName instance using one of the following functions: + + @ref wxfilename() "wxFileName constructors" + + Assign() + + AssignCwd() + + AssignDir() + + AssignHomeDir() + + @ref assigntempfilename() AssignHomeTempFileName + + DirName() + + FileName() + + @ref operatorassign() "operator =" + */ + + + /** + wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS + and VMS formats. Although these formats are quite different, wxFileName tries + to treat them all in the same generic way. It supposes that all file names + consist of the following parts: the volume (also known as drive under Windows + or device under VMS), the path which is a sequence of directory names separated + by the @ref getpathseparators() "path separators" and the full + filename itself which, in turn, is composed from the base file name and the + extension. All of the individual components of the file name may be empty and, + for example, the volume name is always empty under Unix, but if they are all + empty simultaneously, the filename object is considered to be in an invalid + state and IsOk() returns @false for it. + + File names can be case-sensitive or not, the function + IsCaseSensitive() allows to determine this. + + The rules for determining whether the file name is absolute or relative also + depend on the file name format and the only portable way to answer this + question is to use IsAbsolute() or + IsRelative() method. Note that on Windows, "X:" + refers to the current working directory on drive X. Therefore, a wxFileName + instance constructed from for example "X:dir/file.ext" treats the portion + beyond drive separator as being relative to that directory. + + To ensure that the filename is absolute, you may use + MakeAbsolute(). There is also an inverse + function MakeRelativeTo() which undoes + what @ref normalize() Normalize(wxPATH_NORM_DOTS) does. + + Other functions returning information about the file format provided by this + class are GetVolumeSeparator(), + IsPathSeparator(). + */ + + + /** + Before doing other tests, you should use IsOk() to + verify that the filename is well defined. If it is, + FileExists() can be used to test whether a file + with such name exists and DirExists() can be used + to test for directory existence. + + File names should be compared using SameAs() method + or @ref operatorequal() "operator ==". + + For testing basic access modes, you can use: + + IsDirWritable() + + IsDirReadable() + + IsFileWritable() + + IsFileReadable() + + IsFileExecutable() + */ + + + //@{ + /** + Returns @true if the file with this name exists. + + @sa DirExists() + */ + bool FileExists(); + static bool FileExists(const wxString& file); + //@} + + /** + Returns the file name object corresponding to the given @e file. This + function exists mainly for symmetry with DirName(). + */ + static wxFileName FileName(const wxString& file, + wxPathFormat format = wxPATH_NATIVE); + + /** + Retrieves the value of the current working directory on the specified volume. If + the volume is empty, the program's current working directory is returned for the + current volume. + + @returns The string containing the current working directory or an empty + string on error. + + @sa AssignCwd() + */ + static wxString GetCwd(const wxString& volume = ""); + + /** + Returns the number of directories in the file name. + */ + size_t GetDirCount(); + + /** + Returns the directories in string array form. + */ + const wxArrayString GetDirs(); + + /** + Returns the file name extension. + */ + wxString GetExt(); + + /** + Returns the characters that can't be used in filenames and directory names for + the specified format. + */ + static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the canonical path format for this platform. + */ + static wxPathFormat GetFormat(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the full name (including extension but excluding directories). + */ + wxString GetFullName(); + + /** + Returns the full path with name and extension. + */ + wxString GetFullPath(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the home directory. + */ + static wxString GetHomeDir(); + + //@{ + /** + Returns the size of this file (first form) or the given number of bytes (second + form) + in a human-readable form. + + If the size could not be retrieved the @c failmsg string is returned (first + form). + If @c bytes is @c wxInvalidSize or zero, then @c nullsize is returned (second + form). + + In case of success, the returned string is a floating-point number with @c + precision decimal digits + followed by the size unit (B, kB, MB, GB, TB: respectively bytes, kilobytes, + megabytes, gigabytes, terabytes). + */ + wxString GetHumanReadableSize(const wxString& failmsg = "Not available", + int precision = 1); + static wxString GetHumanReadableSize(const wxULongLong& bytes, + const wxString& nullsize = "Not available", + int precision = 1); + //@} + + /** + Return the long form of the path (returns identity on non-Windows platforms) + */ + wxString GetLongPath(); + + /** + Returns the last time the file was last modified. + */ + wxDateTime GetModificationTime(); + + /** + Returns the name part of the filename (without extension). + + @sa GetFullName() + */ + wxString GetName(); + + /** + Returns the path part of the filename (without the name or extension). The + possible flags values are: + + + @b wxPATH_GET_VOLUME + + + Return the path with the volume (does + nothing for the filename formats without volumes), otherwise the path without + volume part is returned. + + @b wxPATH_GET_SEPARATOR + + + Return the path with the trailing + separator, if this flag is not given there will be no separator at the end of + the path. + */ + wxString GetPath(int flags = wxPATH_GET_VOLUME, + wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the usually used path separator for this format. For all formats but + @c wxPATH_DOS there is only one path separator anyhow, but for DOS there + are two of them and the native one, i.e. the backslash is returned by this + method. + + @sa GetPathSeparators() + */ + static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the string containing all the path separators for this format. For all + formats but @c wxPATH_DOS this string contains only one character but for + DOS and Windows both @c '/' and @c '\' may be used as + separators. + + @sa GetPathSeparator() + */ + static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the string of characters which may terminate the path part. This is the + same as GetPathSeparators() except for VMS + path format where ] is used at the end of the path part. + */ + static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the path with the trailing separator, useful for appending the name to + the given path. + + This is the same as calling GetPath() + @c (wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format). + */ + wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE); + + /** + Return the short form of the path (returns identity on non-Windows platforms). + */ + wxString GetShortPath(); + + //@{ + /** + Returns the size of this file (first form) or the size of the given file + (second form). + If the file does not exist or its size could not be read (because e.g. the file + is locked + by another process) the returned value is @c wxInvalidSize. + */ + wxULongLong GetSize(); + static wxULongLong GetSize(const wxString& filename); + //@} + + /** + Returns the directory used for temporary files. + */ + static wxString GetTempDir(); + + /** + Returns the last access, last modification and creation times. The last access + time is updated whenever the file is read or written (or executed in the case + of Windows), last modification time is only changed when the file is written + to. Finally, the creation time is indeed the time when the file was created + under Windows and the inode change time under Unix (as it is impossible to + retrieve the real file creation time there anyhow) which can also be changed + by many operations after the file creation. + + If no filename or extension is specified in this instance of wxFileName + (and therefore IsDir() returns @true) then + this function will return the directory times of the path specified by + GetPath(), otherwise the file times of the + file specified by GetFullPath(). + + Any of the pointers may be @NULL if the corresponding time is not + needed. + + @returns @true on success, @false if we failed to retrieve the times. + */ + bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod, + wxDateTime* dtCreate); + + /** + Returns the string containing the volume for this file name, empty if it + doesn't have one or if the file system doesn't support volumes at all (for + example, Unix). + */ + wxString GetVolume(); + + /** + Returns the string separating the volume from the path for this format. + */ + static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns @true if an extension is present. + */ + bool HasExt(); + + /** + Returns @true if a name is present. + */ + bool HasName(); + + /** + Returns @true if a volume specifier is present. + */ + bool HasVolume(); + + /** + Inserts a directory component before the zero-based position in the directory + list. Please see AppendDir() for important notes. + */ + void InsertDir(size_t before, const wxString& dir); + + /** + Returns @true if this filename is absolute. + */ + bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns @true if the file names of this type are case-sensitive. + */ + static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns @true if this object represents a directory, @false otherwise + (i.e. if it is a file). Note that this method doesn't test whether the + directory or file really exists, you should use + DirExists() or + FileExists() for this. + */ + bool IsDir(); + + //@{ + /** + Returns @true if the directory component of this instance (or given @e dir) + is an existing directory and this process has read permissions on it. + Read permissions on a directory mean that you can list the directory contents + but it + doesn't imply that you have read permissions on the files contained. + */ + bool IsDirReadable(); + static bool IsDirReadable(const wxString& dir); + //@} + + //@{ + /** + Returns @true if the directory component of this instance (or given @e dir) + is an existing directory and this process has write permissions on it. + Write permissions on a directory mean that you can create new files in the + directory. + */ + bool IsDirWritable(); + static bool IsDirWritable(const wxString& dir); + //@} + + //@{ + /** + Returns @true if a file with this name exists and if this process has execute + permissions on it. + */ + bool IsFileExecutable(); + static bool IsFileExecutable(const wxString& file); + //@} + + //@{ + /** + Returns @true if a file with this name exists and if this process has read + permissions on it. + */ + bool IsFileReadable(); + static bool IsFileReadable(const wxString& file); + //@} + + //@{ + /** + Returns @true if a file with this name exists and if this process has write + permissions on it. + */ + bool IsFileWritable(); + static bool IsFileWritable(const wxString& file); + //@} + + /** + Returns @true if the filename is valid, @false if it is not + initialized yet. The assignment functions and + Clear() may reset the object to the uninitialized, + invalid state (the former only do it on failure). + */ +#define bool IsOk() /* implementation is private */ + + /** + Returns @true if the char is a path separator for this format. + */ + static bool IsPathSeparator(wxChar ch, + wxPathFormat format = wxPATH_NATIVE); + + /** + Returns @true if this filename is not absolute. + */ + bool IsRelative(wxPathFormat format = wxPATH_NATIVE); + + /** + On Mac OS, gets the common type and creator for the given extension. + */ + static bool MacFindDefaultTypeAndCreator(const wxString& ext, + wxUint32* type, + wxUint32* creator); + + /** + On Mac OS, registers application defined extensions and their default type and + creator. + */ + static void MacRegisterDefaultTypeAndCreator(const wxString& ext, + wxUint32 type, + wxUint32 creator); + + /** + On Mac OS, looks up the appropriate type and creator from the registration and + then sets it. + */ + bool MacSetDefaultTypeAndCreator(); + + /** + Make the file name absolute. This is a shortcut for + @c wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | + wxPATH_NORM_TILDE, cwd, format). + + @sa MakeRelativeTo(), Normalize(), IsAbsolute() + */ + bool MakeAbsolute(const wxString& cwd = wxEmptyString, + wxPathFormat format = wxPATH_NATIVE); + + /** + This function tries to put this file name in a form relative to + + @param pathBase. + In other words, it returns the file name which should be used to access this + file if the current directory were pathBase. + + pathBase + the directory to use as root, current directory is used by + default + + @param format + the file name format, native by default + + @returns @true if the file name has been changed, @false if we failed to do + anything with it (currently this only happens if the + file name is on a volume different from the volume + specified by pathBase). + + @sa Normalize() + */ + bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, + wxPathFormat format = wxPATH_NATIVE); + + //@{ + /** + @param dir + the directory to create + + @param parm + the permissions for the newly created directory + + @param flags + if the flags contain wxPATH_MKDIR_FULL flag, + try to create each directory in the path and also don't return an error + if the target directory already exists. + + @returns Returns @true if the directory was successfully created, @false + otherwise. + */ + bool Mkdir(int perm = 0777, int flags = 0); + static bool Mkdir(const wxString& dir, int perm = 0777, + int flags = 0); + //@} + + /** + Normalize the path. With the default flags value, the path will be + made absolute, without any ".." and "." and all environment + variables will be expanded in it. + + @param flags + The kind of normalization to do with the file name. It can be + any or-combination of the following constants: + + wxPATH_NORM_ENV_VARS + + + replace env vars with their values + + wxPATH_NORM_DOTS + + + squeeze all .. and . when possible; if there are too many .. and thus they + cannot be all removed, @false will be returned + + wxPATH_NORM_CASE + + + if filesystem is case insensitive, transform to lower case + + wxPATH_NORM_ABSOLUTE + + + make the path absolute prepending cwd + + wxPATH_NORM_LONG + + + make the path the long form + + wxPATH_NORM_SHORTCUT + + + resolve if it is a shortcut (Windows only) + + wxPATH_NORM_TILDE + + + replace ~ and ~user (Unix only) + + wxPATH_NORM_ALL + + + all of previous flags except wxPATH_NORM_CASE + + @param cwd + If not empty, this directory will be used instead of current + working directory in normalization (see wxPATH_NORM_ABSOLUTE). + + @param format + The file name format to use when processing the paths, native by default. + + @returns @true if normalization was successfully or @false otherwise. + */ + bool Normalize(int flags = wxPATH_NORM_ALL, + const wxString& cwd = wxEmptyString, + wxPathFormat format = wxPATH_NATIVE); + + /** + These methods allow to work with the file creation, access and modification + times. Note that not all filesystems under all platforms implement these times + in the same way. For example, the access time under Windows has a resolution of + one day (so it is really the access date and not time). The access time may be + updated when the file is executed or not depending on the platform. + + GetModificationTime() + + GetTimes() + + SetTimes() + + Touch() + + Other file system operations functions are: + + Mkdir() + + Rmdir() + */ + + + /** + Prepends a directory to the file path. Please see + AppendDir() for important notes. + */ + void PrependDir(const wxString& dir); + + /** + Removes the specified directory component from the path. + + @sa GetDirCount() + */ + void RemoveDir(size_t pos); + + /** + Removes last directory component from the path. + */ + void RemoveLastDir(); + + //@{ + /** + Deletes the specified directory from the file system. + */ + bool Rmdir(); + static bool Rmdir(const wxString& dir); + //@} + + /** + Compares the filename using the rules of this platform. + */ + bool SameAs(const wxFileName& filepath, + wxPathFormat format = wxPATH_NATIVE); + + //@{ + /** + Changes the current working directory. + */ + bool SetCwd(); + static bool SetCwd(const wxString& cwd); + //@} + + /** + Sets the extension of the file name to be an empty extension. + This is different from having no extension at all as the file + name will have a trailing dot after a call to this method. + + @sa SetExt(), ClearExt() + */ + void SetEmptyExt(); + + /** + Sets the extension of the file name. Setting an empty string + as the extension will remove the extension resulting in a file + name without a trailing dot, unlike a call to + SetEmptyExt(). + + @sa SetEmptyExt(), ClearExt() + */ + void SetExt(const wxString& ext); + + /** + The full name is the file name and extension (but without the path). + */ + void SetFullName(const wxString& fullname); + + /** + Sets the name part (without extension). + + @sa SetFullName() + */ + void SetName(const wxString& name); + + /** + Sets the file creation and last access/modification times (any of the pointers + may be @NULL). + */ + bool SetTimes(const wxDateTime* dtAccess, + const wxDateTime* dtMod, + const wxDateTime* dtCreate); + + /** + Sets the volume specifier. + */ + void SetVolume(const wxString& volume); + + //@{ + /** + This function splits a full file name into components: the volume (with the + first version) path (including the volume in the second version), the base name + and the extension. Any of the output parameters (@e volume, @e path, + @e name or @e ext) may be @NULL if you are not interested in the + value of a particular component. Also, @e fullpath may be empty on entry. + + On return, @e path contains the file path (without the trailing separator), + @e name contains the file name and @e 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 + @e hasExt instead of relying on testing whether @e ext is empty or not. + */ + static void SplitPath(const wxString& fullpath, wxString* volume, + wxString* path, + wxString* name, + wxString* ext, + bool hasExt = @NULL, + wxPathFormat format = wxPATH_NATIVE); + static void SplitPath(const wxString& fullpath, + wxString* volume, + wxString* path, + wxString* name, + wxString* ext, + wxPathFormat format = wxPATH_NATIVE); + static void SplitPath(const wxString& fullpath, + wxString* path, + wxString* name, + wxString* ext, + wxPathFormat format = wxPATH_NATIVE); + //@} + + /** + Splits the given @e fullpath into the volume part (which may be empty) and + the pure path part, not containing any volume. + + @sa SplitPath() + */ + static void SplitVolume(const wxString& fullpath, + wxString* volume, + wxString* path, + wxPathFormat format = wxPATH_NATIVE); + + /** + Sets the access and modification times to the current moment. + */ + bool Touch(); + + //@{ + /** + Returns @true if the filenames are different. The string @e filenames + is interpreted as a path in the native filename format. + */ + bool operator operator!=(const wxFileName& filename); + bool operator operator!=(const wxString& filename); + //@} + + //@{ + /** + Assigns the new value to this filename object. + */ + wxFileName& operator operator=(const wxFileName& filename); + wxFileName& operator operator=(const wxString& filename); + //@} + + //@{ + /** + Returns @true if the filenames are equal. The string @e filenames is + interpreted as a path in the native filename format. + */ + bool operator operator==(const wxFileName& filename); + bool operator operator==(const wxString& filename); + //@} +}; diff --git a/interface/filepicker.h b/interface/filepicker.h new file mode 100644 index 0000000000..c6c3e27031 --- /dev/null +++ b/interface/filepicker.h @@ -0,0 +1,294 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filepicker.h +// Purpose: documentation for wxFilePickerCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFilePickerCtrl + @wxheader{filepicker.h} + + This control allows the user to select a file. The generic implementation is + a button which brings up a wxFileDialog when clicked. Native implementation + may differ but this is usually a (small) widget which give access to the + file-chooser + dialog. + It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxFLP_DEFAULT_STYLE}: + The default style: includes wxFLP_OPEN | wxFLP_FILE_MUST_EXIST and, + under wxMSW only, wxFLP_USE_TEXTCTRL. + @style{wxFLP_USE_TEXTCTRL}: + Creates a text control to the left of the picker button which is + completely managed by the wxFilePickerCtrl and which can be used by + the user to specify a path (see SetPath). The text control is + automatically synchronized with button's value. Use functions + defined in wxPickerBase to modify the text control. + @style{wxFLP_OPEN}: + Creates a picker which allows the user to select a file to open. + @style{wxFLP_SAVE}: + Creates a picker which allows the user to select a file to save. + @style{wxFLP_OVERWRITE_PROMPT}: + Can be combined with wxFLP_SAVE only: ask confirmation to the user + before selecting a file. + @style{wxFLP_FILE_MUST_EXIST}: + Can be combined with wxFLP_OPEN only: the selected file must be an + existing file. + @style{wxFLP_CHANGE_DIR}: + Change current working directory on each user file selection change. + @endStyleTable + + @library{wxcore} + @category{miscpickers} + @appearance{filepickerctrl.png} + + @seealso + wxFileDialog, wxFileDirPickerEvent +*/ +class wxFilePickerCtrl : public wxPickerBase +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxFilePickerCtrl(wxWindow * parent, wxWindowID id, + const wxString& path = wxEmptyString, + const wxString& message = "Select a file", + const wxString& wildcard = ".", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxFLP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "filepickerctrl"); + + /** + @param parent + Parent window, must not be non-@NULL. + + @param id + The identifier for the control. + + @param path + The initial file shown in the control. Must be a valid path to a file or the + empty string. + + @param message + The message shown to the user in the wxFileDialog shown by the control. + + @param wildcard + A wildcard which defines user-selectable files (use the same syntax as for + wxFileDialog's wildcards). + + @param pos + Initial position. + + @param size + Initial size. + + @param style + The window style, see wxFLP_* flags. + + @param validator + Validator which can be used for additional date checks. + + @param name + Control name. + + @returns @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow * parent, wxWindowID id, + const wxString& path = wxEmptyString, + const wxString& message = "Select a file", + const wxString& wildcard = ".", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxFLP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "filepickerctrl"); + + /** + Similar to GetPath() but returns the path of + the currently selected file as a wxFileName object. + */ + wxFileName GetFileName(); + + /** + Returns the absolute path of the currently selected file. + */ + wxString GetPath(); + + /** + This method does the same thing as SetPath() but + takes a wxFileName object instead of a string. + */ + void SetFileName(const wxFileName & filename); + + /** + Sets the absolute path of the currently selected file. This must be a valid + file if + the @c wxFLP_FILE_MUST_EXIST style was given. + */ + void SetPath(const wxString & filename); +}; + + +/** + @class wxDirPickerCtrl + @wxheader{filepicker.h} + + This control allows the user to select a directory. The generic implementation + is + a button which brings up a wxDirDialog when clicked. Native implementation + may differ but this is usually a (small) widget which give access to the + dir-chooser + dialog. + It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxDIRP_DEFAULT_STYLE}: + The default style: includes wxDIRP_DIR_MUST_EXIST and, under wxMSW + only, wxDIRP_USE_TEXTCTRL. + @style{wxDIRP_USE_TEXTCTRL}: + Creates a text control to the left of the picker button which is + completely managed by the wxDirPickerCtrl and which can be used by + the user to specify a path (see SetPath). The text control is + automatically synchronized with button's value. Use functions + defined in wxPickerBase to modify the text control. + @style{wxDIRP_DIR_MUST_EXIST}: + Creates a picker which allows to select only existing directories. + wxGTK control always adds this flag internally as it does not + support its absence. + @style{wxDIRP_CHANGE_DIR}: + Change current working directory on each user directory selection + change. + @endStyleTable + + @library{wxcore} + @category{miscpickers} + @appearance{dirpickerctrl.png} + + @seealso + wxDirDialog, wxFileDirPickerEvent +*/ +class wxDirPickerCtrl : public wxPickerBase +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxDirPickerCtrl(wxWindow * parent, wxWindowID id, + const wxString& path = wxEmptyString, + const wxString& message = "Select a folder", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDIRP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "dirpickerctrl"); + + /** + @param parent + Parent window, must not be non-@NULL. + + @param id + The identifier for the control. + + @param path + The initial directory shown in the control. Must be a valid path to a directory + or the empty string. + + @param message + The message shown to the user in the wxDirDialog shown by the control. + + @param pos + Initial position. + + @param size + Initial size. + + @param style + The window style, see wxDIRP_* flags. + + @param validator + Validator which can be used for additional date checks. + + @param name + Control name. + + @returns @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow * parent, wxWindowID id, + const wxString& path = wxEmptyString, + const wxString& message = "Select a folder", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDIRP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "dirpickerctrl"); + + /** + Returns the absolute path of the currently selected directory as a wxFileName + object. + This function is equivalent to GetPath() + */ + wxFileName GetDirName(); + + /** + Returns the absolute path of the currently selected directory. + */ + wxString GetPath(); + + /** + Just like SetPath() but this function takes a + wxFileName object. + */ + void SetDirName(const wxFileName & dirname); + + /** + Sets the absolute path of (the default converter uses current locale's + charset)the currently selected directory. This must be a valid directory if + @c wxDIRP_DIR_MUST_EXIST style was given. + */ + void SetPath(const wxString & dirname); +}; + + +/** + @class wxFileDirPickerEvent + @wxheader{filepicker.h} + + This event class is used for the events generated by + wxFilePickerCtrl and by wxDirPickerCtrl. + + @library{wxcore} + @category{FIXME} + + @seealso + wxfilepickerctrl +*/ +class wxFileDirPickerEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxFileDirPickerEvent(wxEventType type, wxObject * generator, + int id, + const wxString path); + + /** + Retrieve the absolute path of the file/directory the user has just selected. + */ + wxString GetPath(); + + /** + Set the absolute path of the file/directory associated with the event. + */ + void SetPath(const wxString & path); +}; diff --git a/interface/filesys.h b/interface/filesys.h new file mode 100644 index 0000000000..9d6b788b5d --- /dev/null +++ b/interface/filesys.h @@ -0,0 +1,341 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filesys.h +// Purpose: documentation for wxFileSystem class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileSystem + @wxheader{filesys.h} + + This class provides an interface for opening files on different + file systems. It can handle absolute and/or local filenames. + It uses a system of handlers to + provide access to user-defined virtual file systems. + + @library{wxbase} + @category{vfs} + + @seealso + wxFileSystemHandler, wxFSFile, Overview +*/ +class wxFileSystem : public wxObject +{ +public: + /** + Constructor. + */ + wxFileSystem(); + + /** + This static function adds new handler into the list of + handlers which provide access to virtual FS. + Note that if two handlers for the same protocol are added, the last one added + takes precedence. + */ + static void AddHandler(wxFileSystemHandler handler); + + /** + Sets the current location. @e location parameter passed to + OpenFile() is relative to this path. + + @b Caution! Unless @e is_dir is @true the @e 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/": + + @param location + the new location. Its meaning depends on the value of is_dir + + @param is_dir + if @true location is new directory. If @false (default) + location is file in the new directory. + */ + void ChangePathTo(const wxString& location, bool is_dir = @false); + + /** + Converts filename into URL. + + @sa URLToFileName(), wxFileName + */ + static wxString FileNameToURL(wxFileName filename); + + /** + Looks for the file with the given name @e file in a colon or semi-colon + (depending on the current platform) separated list of directories in + @e path. If the file is found in any directory, returns @true and the full + path of the file in @e str, otherwise returns @false and doesn't modify + @e str. + + @param str + Receives the full path of the file, must not be @NULL + + @param path + wxPATH_SEP-separated list of directories + + @param file + the name of the file to look for + */ + bool FindFileInPath(wxString str, const wxString& path, + const wxString& file); + + /** + Works like wxFindFirstFile. Returns name of the first + filename (within filesystem's current path) that matches @e wildcard. @e flags + may be one of + wxFILE (only files), wxDIR (only directories) or 0 (both). + */ + wxString FindFirst(const wxString& wildcard, int flags = 0); + + /** + Returns the next filename that matches parameters passed to FindFirst(). + */ + wxString FindNext(); + + /** + Returns actual path (set by wxFileSystem::ChangePathTo). + */ + wxString GetPath(); + + /** + This static function returns @true if there is a registered handler which can + open the given + location. + */ + static bool HasHandlerForPath(const wxString & location); + + /** + Opens the file and returns a pointer to a wxFSFile object + or @NULL if failed. It first tries to open the file in relative scope + (based on value passed to ChangePathTo() method) and then as an + absolute path. Note that the user is responsible for deleting the returned + wxFSFile. + + @e flags can be one or more of the following bit values ored together: + A stream opened with just the default @e wxFS_READ flag may + or may not be seekable depending on the underlying source. + Passing @e wxFS_READ | wxFS_SEEKABLE for @e flags will + back a stream that is not natively seekable with memory or a file + and return a stream that is always seekable. + */ + wxFSFile* OpenFile(const wxString& location, + int flags = wxFS_READ); + + /** + Converts URL into a well-formed filename. The URL must use the @c file + protocol. + */ + static wxFileName URLToFileName(const wxString& url); +}; + + +/** + @class wxFSFile + @wxheader{filesys.h} + + This class represents a single file opened by wxFileSystem. + It provides more information than wxWindow's input stream + (stream, filename, mime type, anchor). + + @b Note: Any pointer returned by a method of wxFSFile is valid + only as long as the wxFSFile object exists. For example a call to GetStream() + doesn't @e create the stream but only returns the pointer to it. In + other words after 10 calls to GetStream() you will have obtained ten identical + pointers. + + @library{wxbase} + @category{vfs} + + @seealso + wxFileSystemHandler, wxFileSystem, Overview +*/ +class wxFSFile : public wxObject +{ +public: + /** + Constructor. You probably won't use it. See Notes for details. + + @param stream + The input stream that will be used to access data + + @param location + The full location (aka filename) of the file + + @param mimetype + MIME type of this file. It may be left empty, in which + case the type will be determined from file's extension (location must + not be empty in this case). + + @param anchor + Anchor. See GetAnchor() for details. + */ + wxFSFile(wxInputStream stream, const wxString& loc, + const wxString& mimetype, + const wxString& anchor, wxDateTime modif); + + /** + Detaches the stream from the wxFSFile object. That is, the + stream obtained with @c GetStream() will continue its existance + after the wxFSFile object is deleted. You will have to delete + the stream yourself. + */ + void DetachStream(); + + /** + Returns anchor (if present). The term of @b anchor can be easily + explained using few examples: + Usually an anchor is presented only if the MIME type is 'text/html'. + But it may have some meaning with other files; + for example myanim.avi#200 may refer to position in animation + or reality.wrl#MyView may refer to a predefined view in VRML. + */ + const wxString GetAnchor(); + + /** + Returns full location of the file, including path and protocol. + Examples : + */ + const wxString GetLocation(); + + /** + Returns the MIME type of the content of this file. It is either + extension-based (see wxMimeTypesManager) or extracted from + HTTP protocol Content-Type header. + */ + const wxString GetMimeType(); + + /** + Returns time when this file was modified. + */ + wxDateTime GetModificationTime(); + + /** + Returns pointer to the stream. You can use the returned + stream to directly access data. You may suppose + that the stream provide Seek and GetSize functionality + (even in the case of the HTTP protocol which doesn't provide + this by default. wxHtml uses local cache to work around + this and to speed up the connection). + */ + wxInputStream* GetStream(); +}; + + +/** + @class wxFileSystemHandler + @wxheader{filesys.h} + + Classes derived from wxFileSystemHandler are used + to access virtual file systems. Its public interface consists + of two methods: wxFileSystemHandler::CanOpen + and wxFileSystemHandler::OpenFile. + It provides additional protected methods to simplify the process + of opening the file: GetProtocol, GetLeftLocation, GetRightLocation, + GetAnchor, GetMimeTypeFromExt. + + Please have a look at overview if you don't know how locations + are constructed. + + Also consult @ref overview_fs "list of available handlers". + + @b wxPerl note: In wxPerl, you need to derive your file system handler class + from Wx::PlFileSystemHandler. + + @library{wxbase} + @category{vfs} + + @seealso + wxFileSystem, wxFSFile, Overview +*/ +class wxFileSystemHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxFileSystemHandler(); + + /** + Returns @true if the handler is able to open this file. This function doesn't + check whether the file exists or not, it only checks if it knows the protocol. + Example: + Must be overridden in derived handlers. + */ + virtual bool CanOpen(const wxString& location); + + /** + Works like wxFindFirstFile. Returns name of the first + filename (within filesystem's current path) that matches @e wildcard. @e flags + may be one of + wxFILE (only files), wxDIR (only directories) or 0 (both). + + This method is only called if CanOpen() returns @true. + */ + virtual wxString FindFirst(const wxString& wildcard, + int flags = 0); + + /** + Returns next filename that matches parameters passed to wxFileSystem::FindFirst. + + This method is only called if CanOpen() returns @true and FindFirst + returned a non-empty string. + */ + virtual wxString FindNext(); + + /** + Returns the anchor if present in the location. + See @ref wxFSFile::getanchor wxFSFile for details. + + Example: GetAnchor("index.htm#chapter2") == "chapter2" + + @b Note: the anchor is NOT part of the left location. + */ + wxString GetAnchor(const wxString& location); + + /** + Returns the left location string extracted from @e location. + + Example: GetLeftLocation("file:myzipfile.zip#zip:index.htm") == + "file:myzipfile.zip" + */ + wxString GetLeftLocation(const wxString& location); + + /** + Returns the MIME type based on @b extension of @e location. (While + wxFSFile::GetMimeType + returns real MIME type - either extension-based or queried from HTTP.) + + Example : GetMimeTypeFromExt("index.htm") == "text/html" + */ + wxString GetMimeTypeFromExt(const wxString& location); + + /** + Returns the protocol string extracted from @e location. + + Example: GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip" + */ + wxString GetProtocol(const wxString& location); + + /** + Returns the right location string extracted from @e location. + + Example : GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm" + */ + wxString GetRightLocation(const wxString& location); + + /** + Opens the file and returns wxFSFile pointer or @NULL if failed. + + Must be overridden in derived handlers. + + @param fs + Parent FS (the FS from that OpenFile was called). See ZIP handler + for details of how to use it. + + @param location + The absolute location of file. + */ + virtual wxFSFile* OpenFile(wxFileSystem& fs, + const wxString& location); +}; diff --git a/interface/font.h b/interface/font.h new file mode 100644 index 0000000000..08c333f786 --- /dev/null +++ b/interface/font.h @@ -0,0 +1,516 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: font.h +// Purpose: documentation for wxFont class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFont + @wxheader{font.h} + + A font is an object which determines the appearance of text. Fonts are + used for drawing text to a device context, and setting the appearance of + a window's text. + + This class uses @ref overview_trefcount "reference counting and copy-on-write" + internally so that assignments between two instances of this class are very + cheap. You can therefore use actual objects instead of pointers without + efficiency problems. If an instance of this class is changed it will create + its own data internally so that other instances, which previously shared the + data using the reference counting, are not affected. + + You can retrieve the current system font settings with wxSystemSettings. + + wxSystemSettings + + @library{wxcore} + @category{gdi} + + @stdobjects + Objects: + wxNullFont + Pointers: + wxNORMAL_FONT + + wxSMALL_FONT + + wxITALIC_FONT + + wxSWISS_FONT + + @seealso + @ref overview_wxfontoverview "wxFont overview", wxDC::SetFont, wxDC::DrawText, + wxDC::GetTextExtent, wxFontDialog, wxSystemSettings +*/ +class wxFont : public wxGDIObject +{ +public: + //@{ + /** + Creates a font object with the specified attributes. + + @param pointSize + Size in points. + + @param pixelSize + Size in pixels: this is directly supported only under MSW + currently where this constructor can be used directly, under other platforms a + font with the closest size to the given one is found using binary search and + the static New method must be used. + + @param family + Font family, a generic way of referring to fonts without specifying actual + facename. One of: + + + wxFONTFAMILY_DEFAULT + + + Chooses a default font. + + wxFONTFAMILY_DECORATIVE + + + A decorative font. + + wxFONTFAMILY_ROMAN + + + A formal, serif font. + + wxFONTFAMILY_SCRIPT + + + A handwriting font. + + wxFONTFAMILY_SWISS + + + A sans-serif font. + + wxFONTFAMILY_MODERN + + + A fixed pitch font. + + wxFONTFAMILY_TELETYPE + + + A teletype font. + + @param style + One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. + + @param weight + Font weight, sometimes also referred to as font boldness. One of: + + + wxFONTWEIGHT_NORMAL + + + Normal font. + + wxFONTWEIGHT_LIGHT + + + Light font. + + wxFONTWEIGHT_BOLD + + + Bold font. + + @param underline + The value can be @true or @false. At present this has an effect on Windows and + Motif 2.x only. + + @param faceName + An optional string specifying the actual typeface to be used. If it is an empty + string, + a default typeface will be chosen based on the family. + + @param encoding + An encoding which may be one of + + wxFONTENCODING_SYSTEM + + + Default system encoding. + + wxFONTENCODING_DEFAULT + + + Default application encoding: this + is the encoding set by calls to + SetDefaultEncoding and which may be set to, + say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the + default application encoding is the same as default system encoding. + + wxFONTENCODING_ISO8859_1...15 + + + ISO8859 encodings. + + wxFONTENCODING_KOI8 + + + The standard Russian encoding for Internet. + + wxFONTENCODING_CP1250...1252 + + + Windows encodings similar to ISO8859 (but not identical). + + If the specified encoding isn't available, no font is created + (see also font encoding overview). + + @remarks If the desired font does not exist, the closest match will be + chosen. Under Windows, only scalable TrueType fonts + are used. + */ + wxFont(); + wxFont(const wxFont& font); + wxFont(int pointSize, wxFontFamily family, int style, + wxFontWeight weight, + const bool underline = @false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + wxFont(const wxSize& pixelSize, wxFontFamily family, + int style, wxFontWeight weight, + const bool underline = @false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + + @remarks Although all remaining fonts are deleted when the application + exits, the application should try to clean up all + fonts itself. This is because wxWidgets cannot know + if a pointer to the font object is stored in an + application data structure, and there is a risk of + double deletion. + */ + ~wxFont(); + + /** + Returns the current application's default encoding. + + @sa @ref overview_wxfontencodingoverview "Font encoding overview", + SetDefaultEncoding() + */ + static wxFontEncoding GetDefaultEncoding(); + + /** + Returns the typeface name associated with the font, or the empty string if + there is no + typeface information. + + @sa SetFaceName() + */ + wxString GetFaceName(); + + /** + Gets the font family. See SetFamily() for a list of valid + family identifiers. + + @sa SetFamily() + */ + wxFontFamily GetFamily(); + + /** + Returns the platform-dependent string completely describing this font. + Returned string is always non-empty. + Note that the returned string is not meant to be shown or edited by the user: a + typical + use of this function is for serializing in string-form a wxFont object. + + @sa SetNativeFontInfo(),GetNativeFontInfoUserDesc() + */ + wxString GetNativeFontInfoDesc(); + + /** + Returns a user-friendly string for this font object. Returned string is always + non-empty. + Some examples of the formats of returned strings (which are platform-dependent) + are in SetNativeFontInfoUserDesc(). + + @sa GetNativeFontInfoDesc() + */ + wxString GetNativeFontInfoUserDesc(); + + /** + Gets the point size. + + @sa SetPointSize() + */ + int GetPointSize(); + + /** + Gets the font style. See wxFont() for a list of valid + styles. + + @sa SetStyle() + */ + int GetStyle(); + + /** + Returns @true if the font is underlined, @false otherwise. + + @sa SetUnderlined() + */ + bool GetUnderlined(); + + /** + Gets the font weight. See wxFont() for a list of valid + weight identifiers. + + @sa SetWeight() + */ + wxFontWeight GetWeight(); + + /** + Returns @true if the font is a fixed width (or monospaced) font, + @false if it is a proportional one or font is invalid. + */ + bool IsFixedWidth(); + + /** + Returns @true if this object is a valid font, @false otherwise. + */ +#define bool IsOk() /* implementation is private */ + + //@{ + /** + These functions take the same parameters as @ref ctor() wxFont + constructor and return a new font object allocated on the heap. + + Using @c New() is currently the only way to directly create a font with + the given size in pixels on platforms other than wxMSW. + */ + static wxFont * New(int pointSize, wxFontFamily family, + int style, + wxFontWeight weight, + const bool underline = @false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont * New(int pointSize, wxFontFamily family, + int flags = wxFONTFLAG_DEFAULT, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont * New(const wxSize& pixelSize, + wxFontFamily family, + int style, + wxFontWeight weight, + const bool underline = @false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont * New(const wxSize& pixelSize, + wxFontFamily family, + int flags = wxFONTFLAG_DEFAULT, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + //@} + + /** + Sets the default font encoding. + + @sa @ref overview_wxfontencodingoverview "Font encoding overview", + GetDefaultEncoding() + */ + static void SetDefaultEncoding(wxFontEncoding encoding); + + /** + Sets the facename for the font. + Returns @true if the given face name exists; @false otherwise. + + @param faceName + A valid facename, which should be on the end-user's system. + + @remarks To avoid portability problems, don't rely on a specific face, + but specify the font family instead or as well. A + suitable font will be found on the end-user's system. + If both the family and the facename are specified, + wxWidgets will first search for the specific face, + and then for a font belonging to the same family. + + @sa GetFaceName(), SetFamily() + */ + bool SetFaceName(const wxString& faceName); + + /** + Sets the font family. + + @param family + One of: + + + wxFONTFAMILY_DEFAULT + + + Chooses a default font. + + wxFONTFAMILY_DECORATIVE + + + A decorative font. + + wxFONTFAMILY_ROMAN + + + A formal, serif font. + + wxFONTFAMILY_SCRIPT + + + A handwriting font. + + wxFONTFAMILY_SWISS + + + A sans-serif font. + + wxFONTFAMILY_MODERN + + + A fixed pitch font. + + wxFONTFAMILY_TELETYPE + + + A teletype font. + + @sa GetFamily(), SetFaceName() + */ + void SetFamily(wxFontFamily family); + + /** + Creates the font corresponding to the given native font description string and + returns @true if + the creation was successful. + which must have been previously returned by + GetNativeFontInfoDesc(). If the string is + invalid, font is unchanged. This function is typically used for de-serializing + a wxFont + object previously saved in a string-form. + + @sa SetNativeFontInfoUserDesc() + */ + bool SetNativeFontInfo(const wxString& info); + + /** + Creates the font corresponding to the given native font description string and + returns @true if + the creation was successful. + Unlike SetNativeFontInfo(), this function accepts + strings which are user-friendly. + Examples of accepted string formats are: + + + Generic syntax + + + Example + + on @b wxGTK2: @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE] + + + Monospace bold 10 + + on @b wxMSW: @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING] + + + Tahoma 10 WINDOWS-1252 + + on @b wxMac: FIXME + + + FIXME + + For more detailed information about the allowed syntaxes you can look at the + documentation of the native API used for font-rendering (e.g. pango_font_description_from_string). + + @sa SetNativeFontInfo() + */ + bool SetNativeFontInfoUserDesc(const wxString& info); + + /** + Sets the point size. + + @param pointSize + Size in points. + + @sa GetPointSize() + */ + void SetPointSize(int pointSize); + + /** + Sets the font style. + + @param style + One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. + + @sa GetStyle() + */ + void SetStyle(int style); + + /** + Sets underlining. + + @param underlining + @true to underline, @false otherwise. + + @sa GetUnderlined() + */ + void SetUnderlined(const bool underlined); + + /** + Sets the font weight. + + @param weight + One of: + + + wxFONTWEIGHT_NORMAL + + + Normal font. + + wxFONTWEIGHT_LIGHT + + + Light font. + + wxFONTWEIGHT_BOLD + + + Bold font. + + @sa GetWeight() + */ + void SetWeight(wxFontWeight weight); + + /** + Inequality operator. + See @ref overview_refcountequality "reference-counted object comparison" for + more info. + */ + bool operator !=(const wxFont& font); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxFont operator =(const wxFont& font); + + /** + Equality operator. + See @ref overview_refcountequality "reference-counted object comparison" for + more info. + */ + bool operator ==(const wxFont& font); +}; diff --git a/interface/fontdlg.h b/interface/fontdlg.h new file mode 100644 index 0000000000..76ba6f6a26 --- /dev/null +++ b/interface/fontdlg.h @@ -0,0 +1,89 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fontdlg.h +// Purpose: documentation for wxFontDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontDialog + @wxheader{fontdlg.h} + + This class represents the font chooser dialog. + + @library{wxcore} + @category{cmndlg} + + @seealso + Overview, wxFontData, wxGetFontFromUser +*/ +class wxFontDialog : public wxDialog +{ +public: + //@{ + /** + Constructor. Pass a parent window, and optionally the + @ref overview_wxfontdata "font data" object to be used to initialize the dialog + controls. If the default constructor is used, + Create() must be called before the dialog can be + shown. + */ + wxFontDialog(); + wxFontDialog(wxWindow* parent); + wxFontDialog(wxWindow* parent, const wxFontData& data); + //@} + + //@{ + /** + Creates the dialog if it the wxFontDialog object had been initialized using the + default constructor. Returns @true on success and @false if an error + occurred. + */ + bool Create(wxWindow* parent); + bool Create(wxWindow* parent, const wxFontData& data); + //@} + + //@{ + /** + Returns the @ref overview_wxfontdata "font data" associated with the font + dialog. + */ + const wxFontData GetFontData(); + wxFontData GetFontData(); + //@} + + /** + Shows the dialog, returning @c wxID_OK if the user pressed Ok, and + @c wxID_CANCEL otherwise. + + If the user cancels the dialog (ShowModal returns @c wxID_CANCEL), no font + will be created. If the user presses OK, a new wxFont will be created and + stored in the font dialog's wxFontData structure. + */ + int ShowModal(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Shows the font selection dialog and returns the font selected by user or + invalid font (use @ref wxFont::isok wxFont:IsOk to test whether a font + is valid) if the dialog was cancelled. + + @param parent + The parent window for the font selection dialog + + @param fontInit + If given, this will be the font initially selected in the dialog. + + @param caption + If given, this will be used for the dialog caption. +*/ +wxFont wxGetFontFromUser(wxWindow * parent, + const wxFont& fontInit, + const wxString& caption = wxEmptyString); + diff --git a/interface/fontenum.h b/interface/fontenum.h new file mode 100644 index 0000000000..3f82b66076 --- /dev/null +++ b/interface/fontenum.h @@ -0,0 +1,86 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fontenum.h +// Purpose: documentation for wxFontEnumerator class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontEnumerator + @wxheader{fontenum.h} + + wxFontEnumerator enumerates either all available fonts on the system or only + the ones with given attributes - either only fixed-width (suited for use in + programs such as terminal emulators and the like) or the fonts available in + the given encoding. + + To do this, you just have to call one of EnumerateXXX() functions - either + wxFontEnumerator::EnumerateFacenames or + wxFontEnumerator::EnumerateEncodings and the + corresponding callback (wxFontEnumerator::OnFacename or + wxFontEnumerator::OnFontEncoding) will be called + repeatedly until either all fonts satisfying the specified criteria are + exhausted or the callback returns @false. + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_wxfontencodingoverview "Font encoding overview", @ref + overview_samplefont "Font sample", wxFont, wxFontMapper +*/ +class wxFontEnumerator +{ +public: + /** + Call OnFontEncoding() for each + encoding supported by the given font - or for each encoding supported by at + least some font if @e font is not specified. + */ + virtual bool EnumerateEncodings(const wxString& font = ""); + + /** + Call OnFacename() for each font which + supports given encoding (only if it is not wxFONTENCODING_SYSTEM) and is of + fixed width (if @e fixedWidthOnly is @true). + + Calling this function with default arguments will result in enumerating all + fonts available on the system. + */ + virtual bool EnumerateFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM, + bool fixedWidthOnly = @false); + + /** + Return array of strings containing all encodings found by + EnumerateEncodings(). + */ + static wxArrayString GetEncodings(const wxString& facename = ""); + + /** + Return array of strings containing all facenames found by + EnumerateFacenames(). + */ + static wxArrayString GetFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM, + bool fixedWidthOnly = @false); + + /** + Returns @true if the given string is valid face name, i.e. it's the face name + of an installed + font and it can safely be used with wxFont::SetFaceName. + */ + static bool IsValidFacename(const wxString & facename); + + /** + Called by EnumerateFacenames() for + each match. Return @true to continue enumeration or @false to stop it. + */ + virtual bool OnFacename(const wxString& font); + + /** + Called by EnumerateEncodings() for + each match. Return @true to continue enumeration or @false to stop it. + */ + virtual bool OnFontEncoding(const wxString& font, + const wxString& encoding); +}; diff --git a/interface/fontmap.h b/interface/fontmap.h new file mode 100644 index 0000000000..7e716591f2 --- /dev/null +++ b/interface/fontmap.h @@ -0,0 +1,179 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fontmap.h +// Purpose: documentation for wxFontMapper class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontMapper + @wxheader{fontmap.h} + + wxFontMapper manages user-definable correspondence between logical font + names and the fonts present on the machine. + + The default implementations of all functions will ask the user if they are + not capable of finding the answer themselves and store the answer in a + config file (configurable via SetConfigXXX functions). This behaviour may + be disabled by giving the value of @false to "interactive" parameter. + + However, the functions will always consult the config file to allow the + user-defined values override the default logic and there is no way to + disable this - which shouldn't be ever needed because if "interactive" was + never @true, the config file is never created anyhow. + + In case everything else fails (i.e. there is no record in config file + and "interactive" is @false or user denied to choose any replacement), + the class queries wxEncodingConverter + for "equivalent" encodings (e.g. iso8859-2 and cp1250) and tries them. + + @library{wxcore} + @category{misc} + + @seealso + wxEncodingConverter, @ref overview_nonenglishoverview "Writing non-English + applications" +*/ +class wxFontMapper +{ +public: + /** + Default ctor. + */ + wxFontMapper(); + + /** + Virtual dtor for a base class. + */ + ~wxFontMapper(); + + /** + Returns the encoding for the given charset (in the form of RFC 2046) or + @c wxFONTENCODING_SYSTEM if couldn't decode it. + + Be careful when using this function with @e interactive set to @true + (default value) as the function then may show a dialog box to the user which + may lead to unexpected reentrancies and may also take a significantly longer + time than a simple function call. For these reasons, it is almost always a bad + idea to call this function from the event handlers for repeatedly generated + events such as @c EVT_PAINT. + */ + wxFontEncoding CharsetToEncoding(const wxString& charset, + bool interactive = @true); + + /** + Get the current font mapper object. If there is no current object, creates + one. + + @sa Set() + */ +#define static wxFontMapper * Get() /* implementation is private */ + + /** + Returns the array of all possible names for the given encoding. The array is + @NULL-terminated. IF it isn't empty, the first name in it is the canonical + encoding name, i.e. the same string as returned by + GetEncodingName(). + */ + static const wxChar** GetAllEncodingNames(wxFontEncoding encoding); + + //@{ + /** + Find an alternative for the given encoding (which is supposed to not be + available on this system). If successful, return @true and fill info + structure with the parameters required to create the font, otherwise + return @false. + + The first form is for wxWidgets' internal use while the second one + is better suitable for general use -- it returns wxFontEncoding which + can consequently be passed to wxFont constructor. + */ + bool GetAltForEncoding(wxFontEncoding encoding, + wxNativeEncodingInfo* info, + const wxString& facename = wxEmptyString, + bool interactive = @true); + bool GetAltForEncoding(wxFontEncoding encoding, + wxFontEncoding* alt_encoding, + const wxString& facename = wxEmptyString, + bool interactive = @true); + //@} + + /** + Returns the @e n-th supported encoding. Together with + GetSupportedEncodingsCount() + this method may be used to get all supported encodings. + */ + static wxFontEncoding GetEncoding(size_t n); + + /** + Return user-readable string describing the given encoding. + */ + static wxString GetEncodingDescription(wxFontEncoding encoding); + + /** + Return the encoding corresponding to the given internal name. This function is + the inverse of GetEncodingName() and is + intentionally less general than + CharsetToEncoding(), i.e. it doesn't + try to make any guesses nor ever asks the user. It is meant just as a way of + restoring objects previously serialized using + GetEncodingName(). + */ + static wxFontEncoding GetEncodingFromName(const wxString& encoding); + + /** + Return internal string identifier for the encoding (see also + wxFontMapper::GetEncodingDescription) + + @sa GetEncodingFromName() + */ + static wxString GetEncodingName(wxFontEncoding encoding); + + /** + Returns the number of the font encodings supported by this class. Together with + GetEncoding() this method may be used to get + all supported encodings. + */ + static size_t GetSupportedEncodingsCount(); + + /** + Check whether given encoding is available in given face or not. + If no facename is given, find @e any font in this encoding. + */ + bool IsEncodingAvailable(wxFontEncoding encoding, + const wxString& facename = wxEmptyString); + + /** + Set the current font mapper object and return previous one (may be @NULL). + This method is only useful if you want to plug-in an alternative font mapper + into wxWidgets. + + @sa Get() + */ +#define static wxFontMapper * Set(wxFontMapper * mapper) /* implementation is private */ + + /** + Set the config object to use (may be @NULL to use default). + + By default, the global one (from wxConfigBase::Get() will be used) + and the default root path for the config settings is the string returned by + GetDefaultConfigPath(). + */ + void SetConfig(wxConfigBase* config); + + /** + Set the root config path to use (should be an absolute path). + */ + void SetConfigPath(const wxString& prefix); + + /** + The parent window for modal dialogs. + */ + void SetDialogParent(wxWindow* parent); + + /** + The title for the dialogs (note that default is quite reasonable). + */ + void SetDialogTitle(const wxString& title); +}; diff --git a/interface/fontpicker.h b/interface/fontpicker.h new file mode 100644 index 0000000000..d0751cfcf4 --- /dev/null +++ b/interface/fontpicker.h @@ -0,0 +1,160 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fontpicker.h +// Purpose: documentation for wxFontPickerCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontPickerCtrl + @wxheader{fontpicker.h} + + This control allows the user to select a font. The generic implementation is + a button which brings up a wxFontDialog when clicked. Native implementation + may differ but this is usually a (small) widget which give access to the + font-chooser + dialog. + It is only available if @c wxUSE_FONTPICKERCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxFNTP_DEFAULT_STYLE}: + The default style: wxFNTP_FONTDESC_AS_LABEL | + wxFNTP_USEFONT_FOR_LABEL. + @style{wxFNTP_USE_TEXTCTRL}: + Creates a text control to the left of the picker button which is + completely managed by the wxFontPickerCtrl and which can be used by + the user to specify a font (see SetSelectedFont). The text control + is automatically synchronized with button's value. Use functions + defined in wxPickerBase to modify the text control. + @style{wxFNTP_FONTDESC_AS_LABEL}: + Keeps the label of the button updated with the fontface name and + the font size. E.g. choosing "Times New Roman bold, italic with + size 10" from the fontdialog, will update the label (overwriting + any previous label) with the "Times New Roman, 10" text. + @style{wxFNTP_USEFONT_FOR_LABEL}: + Uses the currently selected font to draw the label of the button. + @endStyleTable + + @library{wxcore} + @category{miscpickers} + @appearance{fontpickerctrl.png} + + @seealso + wxFontDialog, wxFontPickerEvent +*/ +class wxFontPickerCtrl : public wxPickerBase +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxFontPickerCtrl(wxWindow * parent, wxWindowID id, + const wxFont& font = wxNullFont, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxFNTP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "fontpickerctrl"); + + /** + @param parent + Parent window, must not be non-@NULL. + + @param id + The identifier for the control. + + @param font + The initial font shown in the control. If wxNullFont + is given, the default font is used. + + @param pos + Initial position. + + @param size + Initial size. + + @param style + The window style, see wxFNTP_* flags. + + @param validator + Validator which can be used for additional date checks. + + @param name + Control name. + + @returns @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow * parent, wxWindowID id, + const wxFont& font = wxNullFont, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxFNTP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "fontpickerctrl"); + + /** + Returns the maximum point size value allowed for the user-chosen font. + */ + unsigned int GetMaxPointSize(); + + /** + Returns the currently selected font. + Note that this function is completely different from wxWindow::GetFont. + */ + wxFont GetSelectedFont(); + + /** + Sets the maximum point size value allowed for the user-chosen font. + The default value is 100. Note that big fonts can require a lot of memory and + CPU time + both for creation and for rendering; thus, specially because the user has the + option to specify + the fontsize through a text control (see wxFNTP_USE_TEXTCTRL), it's a good idea + to put a limit + to the maximum font size when huge fonts do not make much sense. + */ + void GetMaxPointSize(unsigned int max); + + /** + Sets the currently selected font. + Note that this function is completely different from wxWindow::SetFont. + */ + void SetSelectedFont(const wxFont & font); +}; + + +/** + @class wxFontPickerEvent + @wxheader{fontpicker.h} + + This event class is used for the events generated by + wxFontPickerCtrl. + + @library{wxcore} + @category{FIXME} + + @seealso + wxFontPickerCtrl +*/ +class wxFontPickerEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxFontPickerEvent(wxObject * generator, int id, + const wxFont& font); + + /** + Retrieve the font the user has just selected. + */ + wxFont GetFont(); + + /** + Set the font associated with the event. + */ + void SetFont(const wxFont & f); +}; diff --git a/interface/frame.h b/interface/frame.h new file mode 100644 index 0000000000..8422651f8c --- /dev/null +++ b/interface/frame.h @@ -0,0 +1,399 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: frame.h +// Purpose: documentation for wxFrame class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFrame + @wxheader{frame.h} + + A frame is a window whose size and position can (usually) be changed by the + user. It usually has thick borders and a title bar, and can optionally contain + a menu bar, toolbar and status bar. A frame can contain any window that is not + a frame or dialog. + + A frame that has a status bar and toolbar created via the + CreateStatusBar/CreateToolBar functions manages these windows, and adjusts the + value returned by GetClientSize to reflect the remaining size available to + application windows. + + @beginStyleTable + @style{wxDEFAULT_FRAME_STYLE}: + Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER | + wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX | wxCLIP_CHILDREN. + @style{wxICONIZE}: + Display the frame iconized (minimized). Windows only. + @style{wxCAPTION}: + Puts a caption on the frame. + @style{wxMINIMIZE}: + Identical to wxICONIZE. Windows only. + @style{wxMINIMIZE_BOX}: + Displays a minimize box on the frame. + @style{wxMAXIMIZE}: + Displays the frame maximized. Windows only. + @style{wxMAXIMIZE_BOX}: + Displays a maximize box on the frame. + @style{wxCLOSE_BOX}: + Displays a close box on the frame. + @style{wxSTAY_ON_TOP}: + Stay on top of all other windows, see also wxFRAME_FLOAT_ON_PARENT. + @style{wxSYSTEM_MENU}: + Displays a system menu. + @style{wxRESIZE_BORDER}: + Displays a resizeable border around the window. + @style{wxFRAME_TOOL_WINDOW}: + Causes a frame with a small titlebar to be created; the frame does + not appear in the taskbar under Windows or GTK+. + @style{wxFRAME_NO_TASKBAR}: + Creates an otherwise normal frame but it does not appear in the + taskbar under Windows or GTK+ (note that it will minimize to the + desktop window under Windows which may seem strange to the users + and thus it might be better to use this style only without + wxMINIMIZE_BOX style). In wxGTK, the flag is respected only if GTK+ + is at least version 2.2 and the window manager supports + _NET_WM_STATE_SKIP_TASKBAR hint. Has no effect under other + platforms. + @style{wxFRAME_FLOAT_ON_PARENT}: + The frame will always be on top of its parent (unlike + wxSTAY_ON_TOP). A frame created with this style must have a + non-@NULL parent. + @style{wxFRAME_EX_CONTEXTHELP}: + Under Windows, puts a query button on the caption. When pressed, + Windows will go into a context-sensitive help mode and wxWidgets + will send a wxEVT_HELP event if the user clicked on an application + window. Note that this is an extended style and must be set by + calling SetExtraStyle before Create is called (two-step + construction). You cannot use this style together with + wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so you should use + wxDEFAULT_FRAME_STYLE ~ (wxMINIMIZE_BOX | wxMAXIMIZE_BOX) for the + frames having this style (the dialogs don't have a minimize or a + maximize box by default) + @style{wxFRAME_SHAPED}: + Windows with this style are allowed to have their shape changed + with the SetShape method. + @style{wxFRAME_EX_METAL}: + On Mac OS X, frames with this style will be shown with a metallic + look. This is an extra style. + @endStyleTable + + @library{wxcore} + @category{managedwnd} + + @seealso + wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog +*/ +class wxFrame : public wxTopLevelWindow +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent. This may be @NULL. If it is non-@NULL, the frame will + always be displayed on top of the parent window on Windows. + + @param id + The window identifier. It may take a value of -1 to indicate a default value. + + @param title + The caption to be displayed on the frame's title bar. + + @param pos + The window position. The value wxDefaultPosition indicates a default position, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param size + The window size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param style + The window style. See wxFrame. + + @param name + The name of the window. This parameter is used to associate a name with the + item, + allowing the application user to set Motif resource values for + individual windows. + + @remarks For Motif, MWM (the Motif Window Manager) should be running for + any window styles to work (otherwise all styles take + effect). + + @sa Create() + */ + wxFrame(); + wxFrame(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + //@} + + /** + Destructor. Destroys all child windows and menu bar if present. + */ + ~wxFrame(); + + /** + Centres the frame on the display. + + @param direction + The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH. + */ + void Centre(int direction = wxBOTH); + + /** + Used in two-step frame construction. See wxFrame() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Creates a status bar at the bottom of the frame. + + @param number + The number of fields to create. Specify a + value greater than 1 to create a multi-field status bar. + + @param style + The status bar style. See wxStatusBar for a list + of valid styles. + + @param id + The status bar window identifier. If -1, an identifier will be chosen by + wxWidgets. + + @param name + The status bar window name. + + @returns A pointer to the status bar if it was created successfully, @NULL + otherwise. + + @remarks The width of the status bar is the whole width of the frame + (adjusted automatically when resizing), and the + height and text size are chosen by the host windowing + system. + + @sa SetStatusText(), OnCreateStatusBar(), GetStatusBar() + */ + virtual wxStatusBar* CreateStatusBar(int number = 1, + long style = 0, + wxWindowID id = -1, + const wxString& name = "statusBar"); + + /** + Creates a toolbar at the top or left of the frame. + + @param style + The toolbar style. See wxToolBar for a list + of valid styles. + + @param id + The toolbar window identifier. If -1, an identifier will be chosen by + wxWidgets. + + @param name + The toolbar window name. + + @returns A pointer to the toolbar if it was created successfully, @NULL + otherwise. + + @remarks By default, the toolbar is an instance of wxToolBar (which is + defined to be a suitable toolbar class on each + platform, such as wxToolBar95). To use a different + class, override OnCreateToolBar(). + + @sa CreateStatusBar(), OnCreateToolBar(), SetToolBar(), + GetToolBar() + */ + virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL, + wxWindowID id = -1, + const wxString& name = "toolBar"); + + /** + Returns the origin of the frame client area (in client coordinates). It may be + different from (0, 0) if the frame has a toolbar. + */ + wxPoint GetClientAreaOrigin(); + + /** + Returns a pointer to the menubar currently associated with the frame (if any). + + @sa SetMenuBar(), wxMenuBar, wxMenu + */ + wxMenuBar* GetMenuBar(); + + /** + Returns a pointer to the status bar currently associated with the frame (if + any). + + @sa CreateStatusBar(), wxStatusBar + */ + wxStatusBar* GetStatusBar(); + + /** + Returns the status bar pane used to display menu and toolbar help. + + @sa SetStatusBarPane() + */ + int GetStatusBarPane(); + + /** + Returns a pointer to the toolbar currently associated with the frame (if any). + + @sa CreateToolBar(), wxToolBar, SetToolBar() + */ + wxToolBar* GetToolBar(); + + /** + Virtual function called when a status bar is requested by CreateStatusBar(). + + @param number + The number of fields to create. + + @param style + The window style. See wxStatusBar for a list + of valid styles. + + @param id + The window identifier. If -1, an identifier will be chosen by + wxWidgets. + + @param name + The window name. + + @returns A status bar object. + + @remarks An application can override this function to return a different + kind of status bar. The default implementation + returns an instance of wxStatusBar. + + @sa CreateStatusBar(), wxStatusBar. + */ + virtual wxStatusBar* OnCreateStatusBar(int number, long style, + wxWindowID id, + const wxString& name); + + /** + Virtual function called when a toolbar is requested by CreateToolBar(). + + @param style + The toolbar style. See wxToolBar for a list + of valid styles. + + @param id + The toolbar window identifier. If -1, an identifier will be chosen by + wxWidgets. + + @param name + The toolbar window name. + + @returns A toolbar object. + + @remarks An application can override this function to return a different + kind of toolbar. The default implementation returns + an instance of wxToolBar. + + @sa CreateToolBar(), wxToolBar. + */ + virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id, + const wxString& name); + + /** + Simulate a menu command. + + @param id + The identifier for a menu item. + */ + void ProcessCommand(int id); + + /** + This function sends a dummy @ref overview_wxsizeevent "size event" to the frame + forcing it to reevaluate its children positions. It is sometimes useful to call + this function after adding or deleting a children after the frame creation or + if a child size changes. + + Note that if the frame is using either sizers or constraints for the children + layout, it is enough to call wxWindow::Layout directly and + this function should not be used in this case. + */ + void SendSizeEvent(); + + /** + Tells the frame to show the given menu bar. + + @param menuBar + The menu bar to associate with the frame. + + @remarks If the frame is destroyed, the menu bar and its menus will be + destroyed also, so do not delete the menu bar + explicitly (except by resetting the frame's menu bar + to another frame or @NULL). + + @sa GetMenuBar(), wxMenuBar, wxMenu. + */ + void SetMenuBar(wxMenuBar* menuBar); + + /** + Associates a status bar with the frame. + + @sa CreateStatusBar(), wxStatusBar, GetStatusBar() + */ + void SetStatusBar(wxStatusBar* statusBar); + + /** + Set the status bar pane used to display menu and toolbar help. + Using -1 disables help display. + */ + void SetStatusBarPane(int n); + + /** + Sets the status bar text and redraws the status bar. + + @param text + The text for the status field. + + @param number + The status field (starting from zero). + + @remarks Use an empty string to clear the status bar. + + @sa CreateStatusBar(), wxStatusBar + */ + virtual void SetStatusText(const wxString& text, int number = 0); + + /** + Sets the widths of the fields in the status bar. + + @param n + The number of fields in the status bar. It must be the + same used in CreateStatusBar. + + @param widths + Must contain an array of n integers, each of which is a status field width + in pixels. A value of -1 indicates that the field is variable width; at least + one + field must be -1. You should delete this array after calling SetStatusWidths. + + @remarks The widths of the variable fields are calculated from the total + width of all fields, minus the sum of widths of the + non-variable fields, divided by the number of + variable fields. + */ + virtual void SetStatusWidths(int n, int * widths); + + /** + Associates a toolbar with the frame. + */ + void SetToolBar(wxToolBar* toolBar); +}; diff --git a/interface/fs_mem.h b/interface/fs_mem.h new file mode 100644 index 0000000000..6500ce5279 --- /dev/null +++ b/interface/fs_mem.h @@ -0,0 +1,119 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fs_mem.h +// Purpose: documentation for wxMemoryFSHandler class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMemoryFSHandler + @wxheader{fs_mem.h} + + This wxFileSystem handler can store arbitrary + data in memory stream and make them accessible via URL. It is particularly + suitable for storing bitmaps from resources or included XPM files so that + they can be used with wxHTML. + + Filenames are prefixed with "memory:", e.g. "memory:myfile.html". + + Example: + + @code + #ifndef __WXMSW__ + #include "logo.xpm" + #endif + + void MyFrame::OnAbout(wxCommandEvent&) + { + wxBusyCursor bcur; + wxFileSystem::AddHandler(new wxMemoryFSHandler); + wxMemoryFSHandler::AddFile("logo.pcx", wxBITMAP(logo), wxBITMAP_TYPE_PCX); + wxMemoryFSHandler::AddFile("about.htm", + "htmlbodyAbout: " + "img src=\"memory:logo.pcx\"/body/html"); + + wxDialog dlg(this, -1, wxString(_("About"))); + wxBoxSizer *topsizer; + wxHtmlWindow *html; + topsizer = new wxBoxSizer(wxVERTICAL); + html = new wxHtmlWindow(, -1, wxDefaultPosition, + wxSize(380, 160), wxHW_SCROLLBAR_NEVER); + html-SetBorders(0); + html-LoadPage("memory:about.htm"); + html-SetSize(html-GetInternalRepresentation()-GetWidth(), + html-GetInternalRepresentation()-GetHeight()); + topsizer-Add(html, 1, wxALL, 10); + topsizer-Add(new wxStaticLine(, -1), 0, wxEXPAND | wxLEFT | wxRIGHT, 10); + topsizer-Add(new wxButton(, wxID_OK, "Ok"), + 0, wxALL | wxALIGN_RIGHT, 15); + dlg.SetAutoLayout(@true); + dlg.SetSizer(topsizer); + topsizer-Fit(); + dlg.Centre(); + dlg.ShowModal(); + + wxMemoryFSHandler::RemoveFile("logo.pcx"); + wxMemoryFSHandler::RemoveFile("about.htm"); + } + @endcode + + @library{wxbase} + @category{FIXME} + + @seealso + wxMemoryFSHandler::AddFileWithMimeType +*/ +class wxMemoryFSHandler : public wxFileSystemHandler +{ +public: + /** + Constructor. + */ + wxMemoryFSHandler(); + + //@{ + /** + Add file to list of files stored in memory. Stored + data (bitmap, text or raw data) + will be copied into private memory stream and available under + name "memory:" + @e filename. + + The @e type argument is one of @c wxBITMAP_TYPE_XXX constants. + Note that you must use a @e type value (aka image format) + that wxWidgets can save (e.g. JPG, PNG, see wxImage + documentation)! + + @sa AddFileWithMimeType() + */ + static void AddFile(const wxString& filename, wxImage& image, + long type); + static void AddFile(const wxString& filename, + const wxBitmap& bitmap, + long type); + //@} + + //@{ + /** + Like AddFile(), but lets you explicitly + specify added file's MIME type. This version should be used whenever you know + the MIME type, because it makes accessing the files faster. + + This function is new since wxWidgets version 2.8.5 + + @sa AddFile() + */ + static void AddFileWithMimeType(const wxString& filename, + const wxString& textdata, + const wxString& mimetype); + static void AddFileWithMimeType(const wxString& filename, + const void* binarydata, + size_t size, + const wxString& mimetype); + //@} + + /** + Remove file from memory FS and free occupied memory. + */ + static void RemoveFile(const wxString& filename); +}; diff --git a/interface/gauge.h b/interface/gauge.h new file mode 100644 index 0000000000..0049b0b1dd --- /dev/null +++ b/interface/gauge.h @@ -0,0 +1,189 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: gauge.h +// Purpose: documentation for wxGauge class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGauge + @wxheader{gauge.h} + + A gauge is a horizontal or vertical bar which shows a quantity (often time). + + wxGauge supports two working modes: determinate and indeterminate progress. + + The first is the usual working mode (see wxGauge::SetValue + and wxGauge::SetRange) while the second can be used when + the program is doing some processing but you don't know how much progress is + being done. + In this case, you can periodically call the wxGauge::Pulse + function to make the progress bar switch to indeterminate mode (graphically + it's usually a set of blocks which move or bounce in the bar control). + + wxGauge supports dynamic switch between these two work modes. + + There are no user commands for the gauge. + + @beginStyleTable + @style{wxGA_HORIZONTAL}: + Creates a horizontal gauge. + @style{wxGA_VERTICAL}: + Creates a vertical gauge. + @style{wxGA_SMOOTH}: + Creates smooth progress bar with one pixel wide update step (not + supported by all platforms). + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{gauge.png} + + @seealso + wxSlider, wxScrollBar +*/ +class wxGauge : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a gauge. + + @param parent + Window parent. + + @param id + Window identifier. + + @param range + Integer range (maximum value) of the gauge. It is ignored when the gauge is + used in indeterminate mode. + + @param pos + Window position. + + @param size + Window size. + + @param style + Gauge style. See wxGauge. + + @param name + Window name. + + @sa Create() + */ + wxGauge(); + wxGauge(wxWindow* parent, wxWindowID id, int range, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxGA_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "gauge"); + //@} + + /** + Destructor, destroying the gauge. + */ + ~wxGauge(); + + /** + Creates the gauge for two-step construction. See wxGauge() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, int range, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxGA_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "gauge"); + + /** + Returns the width of the 3D bezel face. + + @remarks This method is not implemented (returns 0) for most platforms. + + @sa SetBezelFace() + */ + int GetBezelFace(); + + /** + Returns the maximum position of the gauge. + + @sa SetRange() + */ + int GetRange(); + + /** + Returns the 3D shadow margin width. + + @remarks This method is not implemented (returns 0) for most platforms. + + @sa SetShadowWidth() + */ + int GetShadowWidth(); + + /** + Returns the current position of the gauge. + + @sa SetValue() + */ + int GetValue(); + + /** + Returns @true if the gauge is vertical (has @c wxGA_VERTICAL style) and + @false otherwise. + */ + bool IsVertical(); + + /** + Switch the gauge to indeterminate mode (if required) and makes the gauge move + a bit to indicate the user that some progress has been made. + + Note that after calling this function the value returned by GetValue() + is undefined and thus you need to explicitely call SetValue() if you + want to restore the determinate mode. + */ + void Pulse(); + + /** + Sets the 3D bezel face width. + + @remarks This method is not implemented (doesn't do anything) for most + platforms. + + @sa GetBezelFace() + */ + void SetBezelFace(int width); + + /** + Sets the range (maximum value) of the gauge. + This function makes the gauge switch to determinate mode, if it's not already. + + @sa GetRange() + */ + void SetRange(int range); + + /** + Sets the 3D shadow width. + + @remarks This method is not implemented (doesn't do anything) for most + platforms. + */ + void SetShadowWidth(int width); + + /** + Sets the position of the gauge. The @e pos must be between 0 and the gauge + range as returned by GetRange(), inclusive. + + This function makes the gauge switch to determinate mode, if it was in + indeterminate mode before. + + @param pos + Position for the gauge level. + + @sa GetValue() + */ + void SetValue(int pos); +}; diff --git a/interface/gbsizer.h b/interface/gbsizer.h new file mode 100644 index 0000000000..02a33e85fc --- /dev/null +++ b/interface/gbsizer.h @@ -0,0 +1,359 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: gbsizer.h +// Purpose: documentation for wxGBPosition class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGBPosition + @wxheader{gbsizer.h} + + This class represents the position of an item in a virtual grid of + rows and columns managed by a wxGridBagSizer. + + @library{wxcore} + @category{FIXME} +*/ +class wxGBPosition +{ +public: + //@{ + /** + Construct a new wxGBPosition, optionally setting the row and column. + The default is (0,0). + */ + wxGBPosition(); + wxGBPosition(int row, int col); + //@} + + /** + Get the current column value. + */ + int GetCol(); + + /** + Get the current row value. + */ + int GetRow(); + + /** + Set a new column value. + */ + void SetCol(int col); + + /** + Set a new row value. + */ + void SetRow(int row); + + /** + Is the wxGBPosition valid? (An invalid wxGBPosition is (-1,-1). ) + */ + bool operator!(const wxGBPosition& p); + + /** + Compare equality of two wxGBPositions. + */ + bool operator operator==(const wxGBPosition& p); +}; + + +/** + @class wxGridBagSizer + @wxheader{gbsizer.h} + + A wxSizer that can lay out items in a virtual grid + like a wxFlexGridSizer but in this case + explicit positioning of the items is allowed using + wxGBPosition, and items can optionally span + more than one row and/or column using wxGBSpan. + + @library{wxcore} + @category{winlayout} +*/ +class wxGridBagSizer : public wxFlexGridSizer +{ +public: + /** + Constructor, with optional parameters to specify the gap between the + rows and columns. + */ + wxGridBagSizer(int vgap = 0, int hgap = 0); + + //@{ + /** + The Add methods return a valid pointer if the item was successfully placed at + the + given position, @NULL if something was already there. + */ + wxSizerItem* Add(wxWindow* window, const wxGBPosition& pos, + const wxGBSpan& span = wxDefaultSpan, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Add(wxSizer* sizer, const wxGBPosition& pos, + const wxGBSpan& span = wxDefaultSpan, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Add(int width, int height, + const wxGBPosition& pos, + const wxGBSpan& span = wxDefaultSpan, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Add(wxGBSizerItem* item); + //@} + + /** + Called when the managed size of the sizer is needed or when layout + needs done. + */ + wxSize CalcMin(); + + //@{ + /** + Look at all items and see if any intersect (or would overlap) the given + item. Returns @true if so, @false if there would be no overlap. If an + excludeItem is given then it will not be checked for intersection, for + example it may be the item we are checking the position of. + */ + bool CheckForIntersection(wxGBSizerItem* item, + wxGBSizerItem* excludeItem = @NULL); + bool CheckForIntersection(const wxGBPosition& pos, + const wxGBSpan& span, + wxGBSizerItem* excludeItem = @NULL); + //@} + + //@{ + /** + Find the sizer item for the given window or subsizer, returns @NULL if + not found. (non-recursive) + */ + wxGBSizerItem* FindItem(wxWindow* window); + wxGBSizerItem* FindItem(wxSizer* sizer); + //@} + + /** + Return the sizer item located at the point given in pt, or @NULL if + there is no item at that point. The (x,y) coordinates in pt correspond + to the client coordinates of the window using the sizer for + layout. (non-recursive) + */ + wxGBSizerItem* FindItemAtPoint(const wxPoint& pt); + + /** + Return the sizer item for the given grid cell, or @NULL if there is no + item at that position. (non-recursive) + */ + wxGBSizerItem* FindItemAtPosition(const wxGBPosition& pos); + + /** + Return the sizer item that has a matching user data (it only compares + pointer values) or @NULL if not found. (non-recursive) + */ + wxGBSizerItem* FindItemWithData(const wxObject* userData); + + /** + Get the size of the specified cell, including hgap and vgap. Only + valid after a Layout. + */ + wxSize GetCellSize(int row, int col); + + /** + Get the size used for cells in the grid with no item. + */ + wxSize GetEmptyCellSize(); + + //@{ + /** + Get the grid position of the specified item. + */ + wxGBPosition GetItemPosition(wxWindow* window); + wxGBPosition GetItemPosition(wxSizer* sizer); + wxGBPosition GetItemPosition(size_t index); + //@} + + //@{ + /** + Get the row/col spanning of the specified item + */ + wxGBSpan GetItemSpan(wxWindow* window); + wxGBSpan GetItemSpan(wxSizer* sizer); + wxGBSpan GetItemSpan(size_t index); + //@} + + /** + Called when the managed size of the sizer is needed or when layout + needs done. + */ + void RecalcSizes(); + + /** + Set the size used for cells in the grid with no item. + */ + void SetEmptyCellSize(const wxSize& sz); + + //@{ + /** + Set the grid position of the specified item. Returns @true on success. + If the move is not allowed (because an item is already there) then + @false is returned. + */ + bool SetItemPosition(wxWindow* window, const wxGBPosition& pos); + bool SetItemPosition(wxSizer* sizer, const wxGBPosition& pos); + bool SetItemPosition(size_t index, const wxGBPosition& pos); + //@} + + //@{ + /** + Set the row/col spanning of the specified item. Returns @true on + success. If the move is not allowed (because an item is already there) + then @false is returned. + */ + bool SetItemSpan(wxWindow* window, const wxGBSpan& span); + bool SetItemSpan(wxSizer* sizer, const wxGBSpan& span); + bool SetItemSpan(size_t index, const wxGBSpan& span); + //@} +}; + + +/** + @class wxGBSizerItem + @wxheader{gbsizer.h} + + The wxGBSizerItem class is used by the + wxGridBagSizer for tracking the items in the + sizer. It adds grid position and spanning information to the normal + wxSizerItem by adding + wxGBPosition and wxGBSpan + attrbibutes. Most of the time you will not need to use a + wxGBSizerItem directly in your code, but there are a couple of cases + where it is handy. + + @library{wxcore} + @category{FIXME} +*/ +class wxGBSizerItem : public wxSizerItem +{ +public: + //@{ + /** + Construct a sizer item for tracking a subsizer. + */ + wxGBSizerItem(int width, int height, const wxGBPosition& pos, + const wxGBSpan& span, int flag, + int border, wxObject* userData); + wxGBSizerItem(wxWindow* window, const wxGBPosition& pos, + const wxGBSpan& span, + int flag, int border, + wxObject* userData); + wxGBSizerItem(wxSizer* sizer, const wxGBPosition& pos, + const wxGBSpan& span, + int flag, int border, + wxObject* userData); + //@} + + /** + Get the row and column of the endpoint of this item + */ + void GetEndPos(int& row, int& col); + + //@{ + /** + Get the grid position of the item. + */ + wxGBPosition GetPos(); + void GetPos(int& row, int& col); + //@} + + //@{ + /** + Get the row and column spanning of the item. + */ + wxGBSpan GetSpan(); + void GetSpan(int& rowspan, int& colspan); + //@} + + //@{ + /** + Returns @true if the given pos/span would intersect with this item. + */ + bool Intersects(const wxGBSizerItem& other); + bool Intersects(const wxGBPosition& pos, + const wxGBSpan& span); + //@} + + /** + If the item is already a member of a sizer then first ensure that + there is no other item that would intersect with this one at the new + position, then set the new position. Returns @true if the change is + successful and after the next Layout the item will be moved. + */ + bool SetPos(const wxGBPosition& pos); + + /** + If the item is already a member of a sizer then first ensure that + there is no other item that would intersect with this one with its new + spanning size, then set the new spanning. Returns @true if the change + is successful and after the next Layout the item will be resized. + */ + bool SetSpan(const wxGBSpan& span); +}; + + +/** + @class wxGBSpan + @wxheader{gbsizer.h} + + This class is used to hold the row and column spanning attributes of + items in a wxGridBagSizer. + + @library{wxcore} + @category{FIXME} +*/ +class wxGBSpan +{ +public: + //@{ + /** + 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. + */ + wxGBSpan(); + wxGBSpan(int rowspan, int colspan); + //@} + + /** + Get the current colspan value. + */ + int GetColspan(); + + /** + Get the current rowspan value. + */ + int GetRowspan(); + + /** + Set a new colspan value. + */ + void SetColspan(int colspan); + + /** + Set a new rowspan value. + */ + void SetRowspan(int rowspan); + + /** + Is the wxGBSpan valid? (An invalid wxGBSpan is (-1,-1). ) + */ + bool operator!(const wxGBSpan& o); + + /** + Compare equality of two wxGBSpans. + */ + bool operator operator==(const wxGBSpan& o); +}; diff --git a/interface/gdicmn.h b/interface/gdicmn.h new file mode 100644 index 0000000000..fd1f9416fc --- /dev/null +++ b/interface/gdicmn.h @@ -0,0 +1,822 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: gdicmn.h +// Purpose: documentation for wxRealPoint class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRealPoint + @wxheader{gdicmn.h} + + A @b wxRealPoint is a useful data structure for graphics operations. + It contains floating point @e x and @e y members. + See also wxPoint for an integer version. + + @library{wxcore} + @category{data} + + @seealso + wxPoint +*/ +class wxRealPoint +{ +public: + //@{ + /** + Create a point. + + double x + + double y + + Members of the @b wxRealPoint object. + */ + wxRealPoint(); + wxRealPoint(double x, double y); + //@} +}; + + +/** + @class wxRect + @wxheader{gdicmn.h} + + A class for manipulating rectangles. + + @library{wxcore} + @category{data} + + @seealso + wxPoint, wxSize +*/ +class wxRect +{ +public: + //@{ + /** + Creates a wxRect object from size values at the origin. + */ + wxRect(); + wxRect(int x, int y, int width, int height); + wxRect(const wxPoint& topLeft, const wxPoint& bottomRight); + wxRect(const wxPoint& pos, const wxSize& size); + wxRect(const wxSize& size); + //@} + + //@{ + /** + Returns the rectangle having the same size as this one but centered relatively + to the given rectangle @e r. By default, rectangle is centred in both + directions but if @e dir includes only @c wxVERTICAL or only + @c wxHORIZONTAL flag, then it is only centered in this direction while + the other component of its position remains unchanged. + */ + wxRect CentreIn(const wxRect& r, int dir = wxBOTH); + wxRect CenterIn(const wxRect& r, int dir = wxBOTH); + //@} + + //@{ + /** + Returns @true if the given rectangle is completely inside this rectangle + (or touches its boundary) and @false otherwise. + */ + bool Contains(int x, int y); + bool Contains(const wxPoint& pt); + bool Contains(const wxRect& rect); + //@} + + //@{ + /** + Decrease the rectangle size. + + This method is the opposite from Inflate(): + Deflate(a, b) is equivalent to Inflate(-a, -b). + Please refer to Inflate() for full description. + + @sa Inflate() + */ + void Deflate(wxCoord dx, wxCoord dy); + void Deflate(const wxSize& diff); + void Deflate(wxCoord diff); + wxRect Deflate(wxCoord dx, wxCoord dy); + //@} + + /** + Gets the bottom point of the rectangle. + */ + int GetBottom(); + + /** + Gets the position of the bottom left corner. + */ + wxPoint GetBottomLeft(); + + /** + Gets the position of the bottom right corner. + */ + wxPoint GetBottomRight(); + + /** + Gets the height member. + */ + int GetHeight(); + + /** + Gets the left point of the rectangle (the same as wxRect::GetX). + */ + int GetLeft(); + + /** + Gets the position. + */ + wxPoint GetPosition(); + + /** + Gets the right point of the rectangle. + */ + int GetRight(); + + /** + Gets the size. + + @sa SetSize() + */ + wxSize GetSize(); + + /** + Gets the top point of the rectangle (the same as wxRect::GetY). + */ + int GetTop(); + + /** + Gets the position of the top left corner of the rectangle, same as + GetPosition(). + */ + wxPoint GetTopLeft(); + + /** + Gets the position of the top right corner. + */ + wxPoint GetTopRight(); + + /** + Gets the width member. + */ + int GetWidth(); + + /** + Gets the x member. + */ +#define int GetX() /* implementation is private */ + + /** + Gets the y member. + */ +#define int GetY() /* implementation is private */ + + //@{ + /** + Increases the size of the rectangle. + + The second form uses the same @e diff for both @e dx and @e dy. + + The first two versions modify the rectangle in place, the last one returns a + new rectangle leaving this one unchanged. + + The left border is moved farther left and the right border is moved farther + right by @e dx. The upper border is moved farther up and the bottom border + is moved farther down by @e dy. (Note the the width and height of the + rectangle thus change by 2*@e dx and 2*@e dy, respectively.) If one or + both of @e dx and @e dy are negative, the opposite happens: the rectangle + size decreases in the respective direction. + + Inflating and deflating behaves "naturally''. Defined more precisely, that + means: + + "Real'' inflates (that is, @e dx and/or @e dy = 0) are not + constrained. Thus inflating a rectangle can cause its upper left corner + to move into the negative numbers. (the versions prior to 2.5.4 forced + the top left coordinate to not fall below (0, 0), which implied a + forced move of the rectangle.) + + Deflates are clamped to not reduce the width or height of the + rectangle below zero. In such cases, the top-left corner is nonetheless + handled properly. For example, a rectangle at (10, 10) with size (20, + 40) that is inflated by (-15, -15) will become located at (20, 25) at + size (0, 10). Finally, observe that the width and height are treated + independently. In the above example, the width is reduced by 20, + whereas the height is reduced by the full 30 (rather than also stopping + at 20, when the width reached zero). + + @sa Deflate() + */ + void Inflate(wxCoord dx, wxCoord dy); + void Inflate(const wxSize& diff); + void Inflate(wxCoord diff); + wxRect Inflate(wxCoord dx, wxCoord dy); + //@} + + //@{ + /** + Modifies the rectangle to contain the overlapping box of this rectangle and the + one passed in as parameter. The const version returns the new rectangle, the + other one modifies this rectangle in place. + */ + wxRect Intersect(const wxRect& rect); + wxRect Intersect(const wxRect& rect); + //@} + + /** + Returns @true if this rectangle has a non-empty intersection with the + rectangle @e rect and @false otherwise. + */ + bool Intersects(const wxRect& rect); + + /** + Returns @true if this rectangle has a width or height less than or equal to + 0 and @false otherwise. + */ + bool IsEmpty(); + + //@{ + /** + Moves the rectangle by the specified offset. If @e dx is positive, the + rectangle is moved to the right, if @e dy is positive, it is moved to the + bottom, otherwise it is moved to the left or top respectively. + */ + void Offset(wxCoord dx, wxCoord dy); + void Offset(const wxPoint& pt); + //@} + + /** + Sets the height. + */ + void SetHeight(int height); + + /** + Sets the size. + + @sa GetSize() + */ + void SetSize(const wxSize& s); + + /** + Sets the width. + */ + void SetWidth(int width); + + /** + Sets the x position. + */ +#define void SetX(int x) /* implementation is private */ + + /** + Sets the y position. + */ +#define void SetY(int y) /* implementation is private */ + + //@{ + /** + Modifies the rectangle to contain the bounding box of this rectangle and the + one passed in as parameter. The const version returns the new rectangle, the + other one modifies this rectangle in place. + */ + wxRect Union(const wxRect& rect); + wxRect Union(const wxRect& rect); + //@} + + /** + int height + + Height member. + */ + + + //@{ + /** + Returns the intersection of two rectangles (which may be empty). + */ + bool operator !=(const wxRect& r1, const wxRect& r2); + wxRect operator +(const wxRect& r1, const wxRect& r2); + wxRect operator +=(const wxRect& r); + See also wxRect operator *(const wxRect& r1, + const wxRect& r2); + wxRect operator *=(const wxRect& r); + //@} + + /** + Assignment operator. + */ + void operator =(const wxRect& rect); + + /** + Equality operator. + */ + bool operator ==(const wxRect& r1, const wxRect& r2); + + /** + int width + + Width member. + */ + + + /** + int x + + x coordinate of the top-level corner of the rectangle. + */ + + + /** + int y + + y coordinate of the top-level corner of the rectangle. + */ +}; + + +/** + @class wxBrushList + @wxheader{gdicmn.h} + + A brush list is a list containing all brushes which have been created. + + @library{wxcore} + @category{gdi} + + @seealso + wxBrush +*/ +class wxBrushList : public wxList +{ +public: + /** + Constructor. The application should not construct its own brush list: + use the object pointer @b wxTheBrushList. + */ + wxBrushList(); + + /** + Finds a brush with the specified attributes and returns it, else creates a new + brush, adds it + to the brush list, and returns it. + + @param colour + Colour object. + + @param style + Brush style. See wxBrush::SetStyle for a list of styles. + */ + wxBrush * FindOrCreateBrush(const wxColour& colour, + int style = wxSOLID); +}; + + +/** + @class wxPoint + @wxheader{gdicmn.h} + + A @b wxPoint is a useful data structure for graphics operations. + It simply contains integer @e x and @e y members. + + See also wxRealPoint for a floating point version. + + @library{wxcore} + @category{data} + + @seealso + wxRealPoint +*/ +class wxPoint +{ +public: + //@{ + /** + Create a point. + */ + wxPoint(); + wxPoint(int x, int y); + //@} + + //@{ + /** + Operators for sum and subtraction between a wxPoint object and a + wxSize object. + */ + void operator =(const wxPoint& pt); + bool operator ==(const wxPoint& p1, const wxPoint& p2); + bool operator !=(const wxPoint& p1, const wxPoint& p2); + wxPoint operator +(const wxPoint& p1, const wxPoint& p2); + wxPoint operator -(const wxPoint& p1, const wxPoint& p2); + wxPoint operator +=(const wxPoint& pt); + wxPoint operator -=(const wxPoint& pt); + wxPoint operator +(const wxPoint& pt, const wxSize& sz); + wxPoint operator -(const wxPoint& pt, const wxSize& sz); + wxPoint operator +(const wxSize& sz, const wxPoint& pt); + wxPoint operator -(const wxSize& sz, const wxPoint& pt); + wxPoint operator +=(const wxSize& sz); + wxPoint operator -=(const wxSize& sz); + //@} + + /** + int x + + x member. + */ + + + /** + int y + + y member. + */ +}; + + +/** + @class wxColourDatabase + @wxheader{gdicmn.h} + + 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 + wxColourDatabase::AddColour and may use it to look up + colours by names using wxColourDatabase::Find or find the names + for the standard colour suing wxColourDatabase::FindName. + + There is one predefined instance of this class called + @b wxTheColourDatabase. + + @library{wxcore} + @category{FIXME} + + @seealso + wxColour +*/ +class wxColourDatabase +{ +public: + /** + Constructs the colour database. It will be initialized at the first use. + */ + wxColourDatabase(); + + //@{ + /** + Adds a colour to the database. If a colour with the same name already exists, + it is replaced. + + Please note that the overload taking a pointer is deprecated and will be + removed in the next wxWidgets version, please don't use it. + */ + void AddColour(const wxString& colourName, + const wxColour& colour); + void AddColour(const wxString& colourName, wxColour* colour); + //@} + + /** + Finds a colour given the name. Returns an invalid colour object (that is, such + that its @ref wxColour::isok Ok method returns @false) if the colour wasn't + found in the database. + */ + wxColour Find(const wxString& colourName); + + /** + Finds a colour name given the colour. Returns an empty string if the colour is + not found in the database. + */ + wxString FindName(const wxColour& colour); +}; + + +/** + @class wxFontList + @wxheader{gdicmn.h} + + A font list is a list containing all fonts which have been created. There + is only one instance of this class: @b wxTheFontList. Use this object to search + for a previously created font of the desired type and create it if not already + found. + In some windowing systems, the font may be a scarce resource, so it is best to + reuse old resources if possible. When an application finishes, all fonts will + be + deleted and their resources freed, eliminating the possibility of 'memory + leaks'. + + @library{wxcore} + @category{gdi} + + @seealso + wxFont +*/ +class wxFontList : public wxList +{ +public: + /** + Constructor. The application should not construct its own font list: + use the object pointer @b wxTheFontList. + */ + wxFontList(); + + /** + Finds a font of the given specification, or creates one and adds it to the + list. See the @ref wxFont::ctor "wxFont constructor" for + details of the arguments. + */ + wxFont * FindOrCreateFont(int point_size, int family, int style, + int weight, + bool underline = @false, + const wxString& facename = @NULL, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); +}; + + +/** + @class wxSize + @wxheader{gdicmn.h} + + A @b wxSize is a useful data structure for graphics operations. + It simply contains integer @e width and @e height members. + + wxSize is used throughout wxWidgets as well as wxPoint which, although almost + equivalent to wxSize, has a different meaning: wxPoint represents a position + while wxSize - the size. + + @b wxPython note: wxPython defines aliases for the @c x and @c y members + named @c width and @c height since it makes much more sense for + sizes. + + + @library{wxcore} + @category{data} + + @seealso + wxPoint, wxRealPoint +*/ +class wxSize +{ +public: + //@{ + /** + Creates a size object. + */ + wxSize(); + wxSize(int width, int height); + //@} + + //@{ + /** + Decreases the size in x- and y- directions + + By @e size.x and @e size.y for the first overload + By @e dx and @e dy for the second one + By @e d and @e d for the third one + + @sa IncBy() + */ + void DecBy(const wxSize& size); + void DecBy(int dx, int dy); + void DecBy(int d); + //@} + + /** + Decrements this object so that both of its dimensions are not greater than the + corresponding dimensions of the @e size. + + @sa IncTo() + */ + void DecTo(const wxSize& size); + + /** + Gets the height member. + */ + int GetHeight(); + + /** + Gets the width member. + */ + int GetWidth(); + + //@{ + /** + Increases the size in x- and y- directions + + By @e size.x and @e size.y for the first overload + By @e dx and @e dy for the second one + By @e d and @e d for the third one + + @sa DecBy() + */ + void IncBy(const wxSize& size); + void IncBy(int dx, int dy); + void IncBy(int d); + //@} + + /** + Increments this object so that both of its dimensions are not less than the + corresponding dimensions of the @e size. + + @sa DecTo() + */ + void IncTo(const wxSize& size); + + /** + Returns @true if neither of the size object components is equal to -1, which + is used as default for the size values in wxWidgets (hence the predefined + @c wxDefaultSize has both of its components equal to -1). + + This method is typically used before calling + SetDefaults(). + */ + bool IsFullySpecified(); + + //@{ + /** + Operators for division and multiplication between a wxSize object and an + integer. + */ + void operator =(const wxSize& sz); + bool operator ==(const wxSize& s1, const wxSize& s2); + bool operator !=(const wxSize& s1, const wxSize& s2); + wxSize operator +(const wxSize& s1, const wxSize& s2); + wxSize operator -(const wxSize& s1, const wxSize& s2); + wxSize operator +=(const wxSize& sz); + wxSize operator -=(const wxSize& sz); + wxSize operator /(const wxSize& sz, int factor); + wxSize operator *(const wxSize& sz, int factor); + wxSize operator *(int factor, const wxSize& sz); + wxSize operator /=(int factor); + wxSize operator *=(int factor); + //@} + + /** + Scales the dimensions of this object by the given factors. + If you want to scale both dimensions by the same factor you can also use + the @ref operators() "operator *=" + + Returns a reference to this object (so that you can concatenate other + operations in the same line). + */ + wxSize Scale(float xscale, float yscale); + + /** + Sets the width and height members. + */ +#define void Set(int width, int height) /* implementation is private */ + + /** + Combine this size object with another one replacing the default (i.e. equal + to -1) components of this object with those of the other. It is typically + used like this: + + @sa IsFullySpecified() + */ + void SetDefaults(const wxSize& sizeDefault); + + /** + Sets the height. + */ + void SetHeight(int height); + + /** + Sets the width. + */ + void SetWidth(int width); +}; + + +/** + @class wxPenList + @wxheader{gdicmn.h} + + There is only one instance of this class: @b wxThePenList. Use + this object to search for a previously created pen of the desired + type and create it if not already found. In some windowing systems, + the pen may be a scarce resource, so it can pay to reuse old + resources if possible. When an application finishes, all pens will + be deleted and their resources freed, eliminating the possibility of + 'memory leaks'. However, it is best not to rely on this automatic + cleanup because it can lead to double deletion in some circumstances. + + There are two mechanisms in recent versions of wxWidgets which make the + pen list less useful than it once was. Under Windows, scarce resources + are cleaned up internally if they are not being used. Also, a referencing + counting mechanism applied to all GDI objects means that some sharing + of underlying resources is possible. You don't have to keep track of pointers, + working out when it is safe delete a pen, because the referencing counting does + it for you. For example, you can set a pen in a device context, and then + immediately delete the pen you passed, because the pen is 'copied'. + + So you may find it easier to ignore the pen list, and instead create + and copy pens as you see fit. If your Windows resource meter suggests + your application is using too many resources, you can resort to using + GDI lists to share objects explicitly. + + The only compelling use for the pen list is for wxWidgets to keep + track of pens in order to clean them up on exit. It is also kept for + backward compatibility with earlier versions of wxWidgets. + + @library{wxcore} + @category{gdi} + + @seealso + wxPen +*/ +class wxPenList +{ +public: + /** + Constructor. The application should not construct its own pen list: + use the object pointer @b wxThePenList. + */ + wxPenList(); + + //@{ + /** + Finds a pen with the specified attributes and returns it, else creates a new + pen, adds it + to the pen list, and returns it. + + @param colour + Colour object. + + @param colourName + Colour name, which should be in the colour database. + + @param width + Width of pen. + + @param style + Pen style. See wxPen::wxPen for a list of styles. + */ + wxPen* FindOrCreatePen(const wxColour& colour, int width, + int style); + wxPen* FindOrCreatePen(const wxString& colourName, int width, + int style); + //@} +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +//@{ +/** + Returns the dimensions of the work area on the display. On Windows + this means the area not covered by the taskbar, etc. Other platforms + are currently defaulting to the whole display until a way is found to + provide this info for all window managers, etc. +*/ +void wxClientDisplayRect(int * x, int * y, int * width, + int * height); + wxRect wxGetClientDisplayRect(); +//@} + +//@{ +/** + Returns the display size in pixels. +*/ +void wxDisplaySize(int * width, int * height); + wxSize wxGetDisplaySize(); +//@} + +//@{ +/** + Returns the display size in millimeters. +*/ +void wxDisplaySizeMM(int * width, int * height); + wxSize wxGetDisplaySizeMM(); +//@} + +/** + This macro loads an icon from either application resources (on the platforms + for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to + avoid using @c #ifdefs when creating icons. + + @sa @ref overview_wxbitmapoverview "Bitmaps and icons overview", wxBITMAP +*/ +#define wxICON() /* implementation is private */ + +/** + Returns @true if the display is colour, @false otherwise. +*/ +bool wxColourDisplay(); + +/** + This macro loads a bitmap from either application resources (on the platforms + for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to + avoid using @c #ifdefs when creating bitmaps. + + @sa @ref overview_wxbitmapoverview "Bitmaps and icons overview", wxICON +*/ +#define wxBITMAP() /* implementation is private */ + +/** + Returns the depth of the display (a value of 1 denotes a monochrome display). +*/ +int wxDisplayDepth(); + diff --git a/interface/gdiobj.h b/interface/gdiobj.h new file mode 100644 index 0000000000..4c85530443 --- /dev/null +++ b/interface/gdiobj.h @@ -0,0 +1,36 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: gdiobj.h +// Purpose: documentation for wxGDIObject class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGDIObject + @wxheader{gdiobj.h} + + This class allows platforms to implement functionality to optimise GDI objects, + such + as wxPen, wxBrush and wxFont. On Windows, the underling GDI objects are a + scarce resource + and are cleaned up when a usage count goes to zero. On some platforms this + class may not have any special functionality. + + Since the functionality of this class is platform-specific, it is not + documented here in detail. + + @library{wxcore} + @category{FIXME} + + @seealso + wxPen, wxBrush, wxFont +*/ +class wxGDIObject : public wxObject +{ +public: + /** + Default constructor. + */ + wxGDIObject(); +}; diff --git a/interface/glcanvas.h b/interface/glcanvas.h new file mode 100644 index 0000000000..bd51be017c --- /dev/null +++ b/interface/glcanvas.h @@ -0,0 +1,213 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: glcanvas.h +// Purpose: documentation for wxGLContext class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGLContext + @wxheader{glcanvas.h} + + An instance of a wxGLContext represents the state of an OpenGL state machine + and the connection between OpenGL and the system. + + The OpenGL state includes everything that can be set with the OpenGL API: + colors, rendering variables, display lists, texture objects, etc. + Although it is possible to have multiple rendering contexts share display lists + in order to save resources, + this method is hardly used today any more, because display lists are only a + tiny fraction of the overall state. + + Therefore, one rendering context is usually used with or bound to multiple + output windows in turn, + so that the application has access to the complete and identical state while + rendering into each window. + + Binding (making current) a rendering context with another instance of a + wxGLCanvas however works only + if the other wxGLCanvas was created with the same attributes as the wxGLCanvas + from which the wxGLContext + was initialized. (This applies to sharing display lists among contexts + analogously.) + + Note that some wxGLContext features are extremely platform-specific - its best + to check your native platform's glcanvas header (on windows include/wx/msw/glcanvas.h) to see what features your native platform provides. + + @library{wxgl} + @category{gl} + + @seealso + wxGLCanvas +*/ +class wxGLContext : public wxObject +{ +public: + /** + Constructor. + + @param win + The canvas that is used to initialize this context. This parameter is needed + only temporarily, + and the caller may do anything with it (e.g. destroy the window) after the + constructor returned. + + It will be possible to bind (make current) this context to any other wxGLCanvas + that has been created + with equivalent attributes as win. + + @param other + Context to share display lists with or @NULL (the default) for no sharing. + */ + wxGLContext(wxGLCanvas* win, const wxGLContext* other=@NULL); + + /** + Makes the OpenGL state that is represented by this rendering context current + with the wxGLCanvas @e win. + Note that @e win can be a different wxGLCanvas window than the one that was + passed to the constructor of this rendering context. + If @e RC is an object of type wxGLContext, the statements @e + RC.SetCurrent(win); and @e win.SetCurrent(RC); are equivalent, + see wxGLCanvas::SetCurrent. + */ + void SetCurrent(const wxGLCanvas& win); +}; + + +/** + @class wxGLCanvas + @wxheader{glcanvas.h} + + wxGLCanvas is a class for displaying OpenGL graphics. It is always used in + conjunction with wxGLContext as the context can only be + be made current (i.e. active for the OpenGL commands) when it is associated to + a wxGLCanvas. + + More precisely, you first need to create a wxGLCanvas window and then create an + instance of a wxGLContext that is initialized with this + wxGLCanvas and then later use either wxGLCanvas::SetCurrent + with the instance of the wxGLContext or + wxGLContext::SetCurrent with the instance of + the wxGLCanvas (which might be not the same as was used + for the creation of the context) to bind the OpenGL state that is represented + by the rendering context to the canvas, and then finally call + wxGLCanvas::SwapBuffers to swap the buffers of + the OpenGL canvas and thus show your current output. + + Notice that previous versions of wxWidgets used to implicitly create a + wxGLContext inside wxGLCanvas itself. This is still supported in the current + version but is deprecated now and will be removed in the future, please update + your code to create the rendering contexts explicitly. + + To set up the attributes for the canvas (number of bits for the depth buffer, + number of bits for the stencil buffer and so on) you should set up the correct + values of + the @e attribList parameter. The values that should be set up and their + meanings will be described below. + + Notice that OpenGL is not enabled by default. To switch it on, you need to edit + setup.h under Windows and set @c wxUSE_GLCANVAS to 1 (you may also need + to have to add @c opengl32.lib and @c glu32.lib to the list of libraries + your program is linked with). On Unix, pass @c --with-opengl to configure. + + @library{wxgl} + @category{gl} + + @seealso + wxGLContext +*/ +class wxGLCanvas : public wxWindow +{ +public: + /** + Creates a window with the given parameters. Notice that you need to create and + use a wxGLContext to output to this window. + + If + + @param attribList is not specified, double buffered RGBA mode is used. + + parent + Pointer to a parent window. + + @param id + Window identifier. If -1, will automatically create an identifier. + + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets + should generate a default position for the window. + + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should + generate a default size for the window. If no suitable size can be found, the + window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized. + + @param style + Window style. + + @param name + Window name. + + @param attribList + Array of integers. With this parameter you can set the device context + attributes associated to this window. + This array is zero-terminated: it should be set up with constants described in + the table above. + If a constant should be followed by a value, put it in the next array position. + For example, the WX_GL_DEPTH_SIZE should be followed by the value that + indicates the number of + bits for the depth buffer, so: + + @param palette + Palette for indexed colour (i.e. non WX_GL_RGBA) mode. + Ignored under most platforms. + */ + wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY, + const int* attribList = @NULL, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style=0, + const wxString& name="GLCanvas", + const wxPalette& palette = wxNullPalette); + + /** + Determines if a canvas having the specified attributes is available. + + Returns @true if attributes are supported. + + @param attribList + See attribList for wxGLCanvas(). + */ + static bool IsDisplaySupported(const int * attribList = @NULL); + + /** + Sets the current colour for this window (using @c glcolor3f()), using the + wxWidgets colour database to find a named colour. + */ + void SetColour(const wxString& colour); + + /** + Makes the OpenGL state that is represented by the OpenGL rendering context + @e context current, i.e. it will be used by all subsequent OpenGL calls. + + This is equivalent to wxGLContext::SetCurrent + called with this window as parameter. + + Note that this function may only be called when the window is shown on screen, + in particular it can't usually be called from the constructor as the window + isn't yet shown at this moment. + + Returns @false if an error occurred. + */ + bool SetCurrent(const wxGLContext context); + + /** + Swaps the double-buffer of this window, making the back-buffer the front-buffer + and vice versa, + so that the output of the previous OpenGL commands is displayed on the window. + + Returns @false if an error occurred. + */ + bool SwapBuffers(); +}; diff --git a/interface/graphics.h b/interface/graphics.h new file mode 100644 index 0000000000..450a79eb56 --- /dev/null +++ b/interface/graphics.h @@ -0,0 +1,682 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: graphics.h +// Purpose: documentation for wxGraphicsPath class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGraphicsPath + @wxheader{graphics.h} + + A wxGraphicsPath is a native representation of an geometric path. The contents + are specific an private to the respective renderer. Instances are ref counted and can + therefore be assigned as usual. The only way to get a valid instance is via a + CreatePath call on the graphics context or the renderer instance. + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsPath : public wxGraphicsObject +{ +public: + //@{ + /** + + */ + void AddArc(wxDouble x, wxDouble y, wxDouble r, + wxDouble startAngle, + wxDouble endAngle, bool clockwise); + void AddArc(const wxPoint2DDouble& c, wxDouble r, + wxDouble startAngle, + wxDouble endAngle, + bool clockwise); + //@} + + /** + Appends a an arc to two tangents connecting (current) to (x1,y1) and (x1,y1) to + (x2,y2), also a straight line from (current) to (x1,y1). + */ + void AddArcToPoint(wxDouble x1, wxDouble y1, wxDouble x2, + wxDouble y2, + wxDouble r); + + /** + Appends a circle around (x,y) with radius r as a new closed subpath. + */ + void AddCircle(wxDouble x, wxDouble y, wxDouble r); + + //@{ + /** + + */ + void AddCurveToPoint(wxDouble cx1, wxDouble cy1, wxDouble cx2, + wxDouble cy2, + wxDouble x, + wxDouble y); + void AddCurveToPoint(const wxPoint2DDouble& c1, + const wxPoint2DDouble& c2, + const wxPoint2DDouble& e); + //@} + + /** + Appends an ellipse fitting into the passed in rectangle. + */ + void AddEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h); + + //@{ + /** + + */ + void AddLineToPoint(wxDouble x, wxDouble y); + void AddLineToPoint(const wxPoint2DDouble& p); + //@} + + /** + Adds another path. + */ + void AddPath(const wxGraphicsPath& path); + + /** + Adds a quadratic Bezier curve from the current point, using a control point and + an end point. + */ + void AddQuadCurveToPoint(wxDouble cx, wxDouble cy, wxDouble x, + wxDouble y); + + /** + Appends a rectangle as a new closed subpath. + */ + void AddRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h); + + /** + Appends a rounded rectangle as a new closed subpath. + */ + void AddRoundedRectangle(wxDouble x, wxDouble y, wxDouble w, + wxDouble h, + wxDouble radius); + + /** + Closes the current sub-path. + */ + void CloseSubpath(); + + //@{ + /** + Returns @true if the point is within the path. + */ + bool Contains(const wxPoint2DDouble& c, + int fillStyle = wxODDEVEN_RULE); + bool Contains(wxDouble x, wxDouble y, + int fillStyle = wxODDEVEN_RULE); + //@} + + //@{ + /** + Gets the bounding box enclosing all points (possibly including control points). + */ + wxRect2DDouble GetBox(); + void GetBox(wxDouble* x, wxDouble* y, wxDouble* w, + wxDouble* h); + //@} + + //@{ + /** + Gets the last point of the current path, (0,0) if not yet set. + */ + void GetCurrentPoint(wxDouble* x, wxDouble* y); + wxPoint2DDouble GetCurrentPoint(); + //@} + + /** + Returns the native path (CGPathRef for Core Graphics, Path pointer for GDIPlus + and a cairo_path_t pointer for cairo). + */ + void * GetNativePath(); + + //@{ + /** + Begins a new subpath at (x,y) + */ + void MoveToPoint(wxDouble x, wxDouble y); + void MoveToPoint(const wxPoint2DDouble& p); + //@} + + /** + Transforms each point of this path by the matrix. + */ + void Transform(const wxGraphicsMatrix& matrix); + + /** + Gives back the native path returned by GetNativePath() because there might be + some deallocations necessary (eg on cairo the native path returned by + GetNativePath is newly allocated each time). + */ + void UnGetNativePath(void* p); +}; + + +/** + @class wxGraphicsObject + @wxheader{graphics.h} + + This class is the superclass of native graphics objects like pens etc. It + allows reference counting. Not instantiated by user code. + + @library{wxcore} + @category{FIXME} + + @seealso + wxGraphicsBrush, wxGraphicsPen, wxGraphicsMatrix, wxGraphicsPath +*/ +class wxGraphicsObject : public wxObject +{ +public: + /** + Returns the renderer that was used to create this instance, or @NULL if it has + not been initialized yet + */ + wxGraphicsRenderer* GetRenderer(); + + /** + Is this object valid (@false) or still empty (@true)? + */ + bool IsNull(); +}; + + +/** + @class wxGraphicsContext + @wxheader{graphics.h} + + A wxGraphicsContext instance is the object that is drawn upon. It is created by + a renderer using the CreateContext calls.., this can be either directly using a renderer + instance, or indirectly using the static convenience CreateXXX functions of + wxGraphicsContext that always delegate the task to the default renderer. + + @library{wxcore} + @category{FIXME} + + @seealso + wxGraphicsRenderer:: CreateContext +*/ +class wxGraphicsContext : public wxGraphicsObject +{ +public: + //@{ + /** + Clips drawings to the rectangle. + */ + void Clip(const wxRegion& region); + void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h); + //@} + + /** + Concatenates the passed in transform with the current transform of this context + */ + void ConcatTransform(const wxGraphicsMatrix& matrix); + + //@{ + /** + Creates a wxGraphicsContext from a wxWindow. + + @sa wxGraphicsRenderer:: CreateContext + */ + wxGraphicsContext* Create(const wxWindowDC& dc); + wxGraphicsContext* Create(wxWindow* window); + //@} + + /** + Creates a native brush from a wxBrush. + */ + wxGraphicsBrush CreateBrush(const wxBrush& brush); + + /** + Creates a native graphics font from a wxFont and a text colour. + */ + wxGraphicsFont CreateFont(const wxFont& font, + const wxColour& col = wxBLACK); + + /** + Creates a wxGraphicsContext from a native context. This native context must be + eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a + cairo_t pointer for cairo. + + Creates a wxGraphicsContext from a native window. + + @sa wxGraphicsRenderer:: CreateContextFromNativeContext + */ + wxGraphicsContext* CreateFromNative(void * context); + + /** + @sa wxGraphicsRenderer:: CreateContextFromNativeWindow + */ + wxGraphicsContext* CreateFromNativeWindow(void * window); + + /** + Creates a native brush, having a linear gradient, starting at (x1,y1) with + color c1 to (x2,y2) with color c2 + */ + wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1, + wxDouble y1, + wxDouble x2, + wxDouble y2, + const wxColouramp;c1, + const wxColouramp;c2); + + /** + Creates a native affine transformation matrix from the passed in values. The + defaults result in an identity matrix. + */ + wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0, + wxDouble c = 0.0, + wxDouble d = 1.0, + wxDouble tx = 0.0, + wxDouble ty = 0.0); + + /** + Creates a native graphics path which is initially empty. + */ + wxGraphicsPath CreatePath(); + + /** + Creates a native pen from a wxPen. + */ + wxGraphicsPen CreatePen(const wxPen& pen); + + /** + Creates a native brush, having a radial gradient originating at (xo,yc) with + color oColour and ends on a circle around (xc,yc) with radius r and color cColour + */ + wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, + wxDouble yo, + wxDouble xc, + wxDouble yc, + wxDouble radius, + const wxColour& oColor, + const wxColour& cColor); + + /** + Draws the bitmap. In case of a mono bitmap, this is treated as a mask and the + current brushed is used for filling. + */ + void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y, + wxDouble w, wxDouble h); + + /** + Draws an ellipse. + */ + void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h); + + /** + Draws the icon. + */ + void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y, + wxDouble w, wxDouble h); + + /** + Draws a polygon. + */ + void DrawLines(size_t n, const wxPoint2DDouble* points, + int fillStyle = wxODDEVEN_RULE); + + /** + Draws the path by first filling and then stroking. + */ + void DrawPath(const wxGraphicsPath& path, + int fillStyle = wxODDEVEN_RULE); + + /** + Draws a rectangle. + */ + void DrawRectangle(wxDouble x, wxDouble y, wxDouble w, + wxDouble h); + + /** + Draws a rounded rectangle. + */ + void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w, + wxDouble h, + wxDouble radius); + + //@{ + /** + Draws a text at the defined position, at the given angle. + */ + void DrawText(const wxString& str, wxDouble x, wxDouble y, + wxDouble angle); + void DrawText(const wxString& str, wxDouble x, wxDouble y); + //@} + + /** + Fills the path with the current brush. + */ + void FillPath(const wxGraphicsPath& path, + int fillStyle = wxODDEVEN_RULE); + + /** + Returns the native context (CGContextRef for Core Graphics, Graphics pointer + for GDIPlus and cairo_t pointer for cairo). + */ + void * GetNativeContext(); + + /** + Fills the @e widths array with the widths from the beginning of + @e text to the corresponding character of @e text. + */ + void GetPartialTextExtents(const wxString& text, + wxArrayDouble& widths); + + /** + Gets the dimensions of the string using the currently selected font. + @e string is the text string to measure, @e w and @e h are + the total width and height respectively, @e descent is the + dimension from the baseline of the font to the bottom of the + descender, and @e externalLeading is any extra vertical space added + to the font by the font designer (usually is zero). + */ + void GetTextExtent(const wxString& text, wxDouble* width, + wxDouble* height, + wxDouble* descent, + wxDouble* externalLeading); + + /** + Gets the current transformation matrix of this context. + */ + wxGraphicsMatrix GetTransform(); + + /** + Resets the clipping to original shape. + */ + void ResetClip(); + + /** + Rotates the current transformation matrix (radians), + */ + void Rotate(wxDouble angle); + + /** + Scales the current transformation matrix. + */ + void Scale(wxDouble xScale, wxDouble yScale); + + //@{ + /** + Sets the brush for filling paths. + */ + void SetBrush(const wxBrush& brush); + void SetBrush(const wxGraphicsBrush& brush); + //@} + + //@{ + /** + Sets the font for drawing text. + */ + void SetFont(const wxFont& font, const wxColour& colour); + void SetFont(const wxGraphicsFont& font); + //@} + + //@{ + /** + Sets the pen used for stroking. + */ + void SetPen(const wxGraphicsPen& pen); + void SetPen(const wxPen& pen); + //@} + + /** + Sets the current transformation matrix of this context + */ + void SetTransform(const wxGraphicsMatrix& matrix); + + /** + Strokes a single line. + */ + void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2, + wxDouble y2); + + //@{ + /** + Stroke disconnected lines from begin to end points, fastest method available + for this purpose. + */ + void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints, + const wxPoint2DDouble* endPoints); + void StrokeLines(size_t n, const wxPoint2DDouble* points); + //@} + + /** + Strokes along a path with the current pen. + */ + void StrokePath(const wxGraphicsPath& path); + + /** + Translates the current transformation matrix. + */ + void Translate(wxDouble dx, wxDouble dy); +}; + + +/** + @class wxGraphicsRenderer + @wxheader{graphics.h} + + A wxGraphicsRenderer is the instance corresponding to the rendering engine + used. There may be multiple instances on a system, if there are different rendering engines present, but there is always one instance per engine, eg there is ONE core graphics renderer instance on OSX. This instance is pointed back to by all objects created by it (wxGraphicsContext, wxGraphicsPath etc). Therefore you can create ag additional instances of paths etc. by calling GetRenderer() and then using the appropriate CreateXXX function. + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsRenderer : public wxObject +{ +public: + /** + Creates a native brush from a wxBrush. + */ + wxGraphicsBrush CreateBrush(const wxBrush& brush); + + //@{ + /** + Creates a wxGraphicsContext from a wxWindow. + */ + wxGraphicsContext * CreateContext(const wxWindowDC& dc); + wxGraphicsContext * CreateContext(wxWindow* window); + //@} + + /** + Creates a wxGraphicsContext from a native context. This native context must be + eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t pointer for cairo. + */ + wxGraphicsContext * CreateContextFromNativeContext(void * context); + + /** + Creates a wxGraphicsContext from a native window. + */ + wxGraphicsContext * CreateContextFromNativeWindow(void * window); + + /** + Creates a native graphics font from a wxFont and a text colour. + */ + wxGraphicsFont CreateFont(const wxFont& font, + const wxColour& col = wxBLACK); + + /** + Creates a native brush, having a linear gradient, starting at (x1,y1) with + color c1 to (x2,y2) with color c2 + */ + wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1, + wxDouble y1, + wxDouble x2, + wxDouble y2, + const wxColouramp;c1, + const wxColouramp;c2); + + /** + Creates a native affine transformation matrix from the passed in values. The + defaults result in an identity matrix. + */ + wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0, + wxDouble c = 0.0, + wxDouble d = 1.0, + wxDouble tx = 0.0, + wxDouble ty = 0.0); + + /** + Creates a native graphics path which is initially empty. + */ + wxGraphicsPath CreatePath(); + + /** + Creates a native pen from a wxPen. + */ + wxGraphicsPen CreatePen(const wxPen& pen); + + /** + Creates a native brush, having a radial gradient originating at (xo,yc) with + color oColour and ends on a circle around (xc,yc) with radius r and color cColour + */ + wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, + wxDouble yo, + wxDouble xc, + wxDouble yc, + wxDouble radius, + const wxColour& oColour, + const wxColour& cColour); + + /** + Returns the default renderer on this platform. On OS X this is the Core + Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the cairo renderer. + */ + wxGraphicsRenderer* GetDefaultRenderer(); +}; + + +/** + @class wxGraphicsBrush + @wxheader{graphics.h} + + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsBrush : public wxGraphicsObject +{ +public: + +}; + + +/** + @class wxGraphicsFont + @wxheader{graphics.h} + + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsFont : public wxGraphicsObject +{ +public: + +}; + + +/** + @class wxGraphicsPen + @wxheader{graphics.h} + + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsPen : public wxGraphicsObject +{ +public: + +}; + + +/** + @class wxGraphicsMatrix + @wxheader{graphics.h} + + A wxGraphicsMatrix is a native representation of an affine matrix. The contents + are specific and private to the respective renderer. Instances are ref counted and can therefore be assigned as usual. The only way to get a valid instance is via a CreateMatrix call on the graphics context or the renderer instance. + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsMatrix : public wxGraphicsObject +{ +public: + //@{ + /** + + */ + void Concat(const wxGraphicsMatrix* t); + void Concat(const wxGraphicsMatrix& t); + //@} + + /** + Returns the component values of the matrix via the argument pointers. + */ +#define void Get(wxDouble* a=@NULL, wxDouble* b=@NULL, wxDouble* c=@NULL, + wxDouble* d=@NULL, wxDouble* tx=@NULL, + wxDouble* ty=@NULL) /* implementation is private */ + + /** + Returns the native representation of the matrix. For CoreGraphics this is a + CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer. + */ + void * GetNativeMatrix(); + + /** + Inverts the matrix. + */ + void Invert(); + + /** + Returns @true if the elements of the transformation matrix are equal. + */ + bool IsEqual(const wxGraphicsMatrix& t); + + /** + Return @true if this is the identity matrix. + */ + bool IsIdentity(); + + /** + Rotates this matrix (radians). + */ + void Rotate(wxDouble angle); + + /** + Scales this matrix. + */ + void Scale(wxDouble xScale, wxDouble yScale); + + /** + Sets the matrix to the respective values (default values are the identity + matrix) + */ +#define void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0, + wxDouble d = 1.0, wxDouble tx = 0.0, + wxDouble ty = 0.0) /* implementation is private */ + + /** + Applies this matrix to a distance (ie. performs all transforms except + translations) + */ + void TransformDistance(wxDouble* dx, wxDouble* dy); + + /** + Applies this matrix to a point. + */ + void TransformPoint(wxDouble* x, wxDouble* y); + + /** + Translates this matrix. + */ + void Translate(wxDouble dx, wxDouble dy); +}; diff --git a/interface/grid.h b/interface/grid.h new file mode 100644 index 0000000000..a542437f7f --- /dev/null +++ b/interface/grid.h @@ -0,0 +1,2858 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: grid.h +// Purpose: documentation for wxGridCellFloatRenderer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGridCellFloatRenderer + @wxheader{grid.h} + + This class may be used to format floating point data in a cell. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellRenderer, wxGridCellNumberRenderer, wxGridCellStringRenderer, + wxGridCellBoolRenderer +*/ +class wxGridCellFloatRenderer : public wxGridCellStringRenderer +{ +public: + /** + @param width + Minimum number of characters to be shown. + + @param precision + Number of digits after the decimal dot. + */ + wxGridCellFloatRenderer(int width = -1, int precision = -1); + + /** + Returns the precision ( see @ref constr() wxGridCellFloatRenderer ). + */ + int GetPrecision(); + + /** + Returns the width ( see @ref constr() wxGridCellFloatRenderer ). + */ + int GetWidth(); + + /** + Parameters string format is "width[,precision]". + */ + void SetParameters(const wxString& params); + + /** + Sets the precision ( see @ref constr() wxGridCellFloatRenderer ). + */ + void SetPrecision(int precision); + + /** + Sets the width ( see @ref constr() wxGridCellFloatRenderer ) + */ + void SetWidth(int width); +}; + + +/** + @class wxGridTableBase + @wxheader{grid.h} + + Grid table classes. + + @library{wxadv} + @category{FIXME} +*/ +class wxGridTableBase : public wxObject +{ +public: + /** + + */ + wxGridTableBase(); + + /** + + */ + ~wxGridTableBase(); + + /** + + */ + bool AppendCols(size_t numCols = 1); + + /** + + */ + bool AppendRows(size_t numRows = 1); + + /** + + */ + bool CanGetValueAs(int row, int col, const wxString& typeName); + + /** + Does this table allow attributes? Default implementation creates + a wxGridCellAttrProvider if necessary. + */ + bool CanHaveAttributes(); + + /** + + */ + bool CanSetValueAs(int row, int col, const wxString& typeName); + + /** + + */ + void Clear(); + + /** + + */ + bool DeleteCols(size_t pos = 0, size_t numCols = 1); + + /** + + */ + bool DeleteRows(size_t pos = 0, size_t numRows = 1); + + /** + by default forwarded to wxGridCellAttrProvider if any. May be + overridden to handle attributes directly in the table. + */ + wxGridCellAttr* GetAttr(int row, int col); + + /** + get the currently used attr provider (may be @NULL) + */ + wxGridCellAttrProvider* GetAttrProvider(); + + /** + + */ + wxString GetColLabelValue(int col); + + /** + + */ + int GetNumberCols(); + + /** + You must override these functions in a derived table class. + */ + int GetNumberRows(); + + /** + + */ + wxString GetRowLabelValue(int row); + + /** + Data type determination and value access. + */ + wxString GetTypeName(int row, int col); + + /** + + */ + wxString GetValue(int row, int col); + + /** + + */ + bool GetValueAsBool(int row, int col); + + /** + For user defined types + */ + void* GetValueAsCustom(int row, int col, + const wxString& typeName); + + /** + + */ + double GetValueAsDouble(int row, int col); + + /** + + */ + long GetValueAsLong(int row, int col); + + /** + + */ + wxGrid * GetView(); + + /** + + */ + bool InsertCols(size_t pos = 0, size_t numCols = 1); + + /** + + */ + bool InsertRows(size_t pos = 0, size_t numRows = 1); + + /** + + */ + bool IsEmptyCell(int row, int col); + + /** + these functions take ownership of the pointer + */ + void SetAttr(wxGridCellAttr* attr, int row, int col); + + /** + Attribute handling + give us the attr provider to use - we take ownership of the pointer + */ + void SetAttrProvider(wxGridCellAttrProvider* attrProvider); + + /** + + */ + void SetColAttr(wxGridCellAttr* attr, int col); + + /** + , @b const@e wxString) + */ + void SetColLabelValue(); + + /** + + */ + void SetRowAttr(wxGridCellAttr* attr, int row); + + /** + , @b const@e wxString) + */ + void SetRowLabelValue(); + + /** + + */ + void SetValue(int row, int col, const wxString& value); + + /** + + */ + void SetValueAsBool(int row, int col, bool value); + + /** + + */ + void SetValueAsCustom(int row, int col, const wxString& typeName, + void* value); + + /** + + */ + void SetValueAsDouble(int row, int col, double value); + + /** + + */ + void SetValueAsLong(int row, int col, long value); + + /** + Overriding these is optional + */ + void SetView(wxGrid* grid); + + /** + + */ + void UpdateAttrCols(size_t pos, int numCols); + + /** + change row/col number in attribute if needed + */ + void UpdateAttrRows(size_t pos, int numRows); +}; + + +/** + @class wxGridCellEditor + @wxheader{grid.h} + + This class is responsible for providing and manipulating + the in-place edit controls for the grid. Instances of wxGridCellEditor + (actually, instances of derived classes since it is an abstract class) can be + associated with the cell attributes for individual cells, rows, columns, or + even for the entire grid. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellTextEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, + wxGridCellNumberEditor, wxGridCellChoiceEditor +*/ +class wxGridCellEditor +{ +public: + /** + + */ + wxGridCellEditor(); + + /** + The dtor is private because only DecRef() can delete us. + */ + ~wxGridCellEditor(); + + /** + Fetch the value from the table and prepare the edit control + to begin editing. Set the focus to the edit control. + */ + void BeginEdit(int row, int col, wxGrid* grid); + + /** + Create a new object which is the copy of this one. + */ + wxGridCellEditor* Clone(); + + /** + Creates the actual edit control. + */ + void Create(wxWindow* parent, wxWindowID id, + wxEvtHandler* evtHandler); + + /** + Final cleanup. + */ + void Destroy(); + + /** + Complete the editing of the current cell. Returns @true if the value has + changed. If necessary, the control may be destroyed. + */ + bool EndEdit(int row, int col, wxGrid* grid); + + /** + Some types of controls on some platforms may need some help + with the Return key. + */ + void HandleReturn(wxKeyEvent& event); + + /** + + */ + bool IsCreated(); + + /** + Draws the part of the cell not occupied by the control: the base class + version just fills it with background colour from the attribute. + */ + void PaintBackground(const wxRect& rectCell, + wxGridCellAttr* attr); + + /** + Reset the value in the control back to its starting value. + */ + void Reset(); + + /** + Size and position the edit control. + */ + void SetSize(const wxRect& rect); + + /** + Show or hide the edit control, use the specified attributes to set + colours/fonts for it. + */ + void Show(bool show, wxGridCellAttr* attr = @NULL); + + /** + If the editor is enabled by clicking on the cell, this method will be + called. + */ + void StartingClick(); + + /** + If the editor is enabled by pressing keys on the grid, + this will be called to let the editor do something about + that first key if desired. + */ + void StartingKey(wxKeyEvent& event); +}; + + +/** + @class wxGridCellTextEditor + @wxheader{grid.h} + + The editor for string/text data. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, + wxGridCellNumberEditor, wxGridCellChoiceEditor +*/ +class wxGridCellTextEditor : public wxGridCellEditor +{ +public: + /** + Default constructor. + */ + wxGridCellTextEditor(); + + /** + The parameters string format is "n" where n is a number representing the + maximum width. + */ + void SetParameters(const wxString& params); +}; + + +/** + @class wxGridCellStringRenderer + @wxheader{grid.h} + + This class may be used to format string data in a cell; it is the default + for string cells. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellRenderer, wxGridCellNumberRenderer, wxGridCellFloatRenderer, + wxGridCellBoolRenderer +*/ +class wxGridCellStringRenderer : public wxGridCellRenderer +{ +public: + /** + Default constructor + */ + wxGridCellStringRenderer(); +}; + + +/** + @class wxGridCellChoiceEditor + @wxheader{grid.h} + + The editor for string data allowing to choose from a list of strings. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, + wxGridCellTextEditor, wxGridCellNumberEditor +*/ +class wxGridCellChoiceEditor : public wxGridCellEditor +{ +public: + //@{ + /** + @param count + Number of strings from which the user can choose. + + @param choices + An array of strings from which the user can choose. + + @param allowOthers + If allowOthers is @true, the user can type a string not in choices array. + */ + wxGridCellChoiceEditor(size_t count = 0, + const wxString choices[] = @NULL, + bool allowOthers = @false); + wxGridCellChoiceEditor(const wxArrayString& choices, + bool allowOthers = @false); + //@} + + /** + Parameters string format is "item1[,item2[...,itemN]]" + */ + void SetParameters(const wxString& params); +}; + + +/** + @class wxGridEditorCreatedEvent + @wxheader{grid.h} + + + @library{wxadv} + @category{FIXME} +*/ +class wxGridEditorCreatedEvent : public wxCommandEvent +{ +public: + //@{ + /** + + */ + wxGridEditorCreatedEvent(); + wxGridEditorCreatedEvent(int id, wxEventType type, + wxObject* obj, + int row, + int col, + wxControl* ctrl); + //@} + + /** + Returns the column at which the event occurred. + */ + int GetCol(); + + /** + Returns the edit control. + */ + wxControl* GetControl(); + + /** + Returns the row at which the event occurred. + */ + int GetRow(); + + /** + Sets the column at which the event occurred. + */ + void SetCol(int col); + + /** + Sets the edit control. + */ + void SetControl(wxControl* ctrl); + + /** + Sets the row at which the event occurred. + */ + void SetRow(int row); +}; + + +/** + @class wxGridRangeSelectEvent + @wxheader{grid.h} + + + @library{wxadv} + @category{FIXME} +*/ +class wxGridRangeSelectEvent : public wxNotifyEvent +{ +public: + //@{ + /** + + */ + wxGridRangeSelectEvent(); + wxGridRangeSelectEvent(int id, wxEventType type, + wxObject* obj, + const wxGridCellCoords& topLeft, + const wxGridCellCoords& bottomRight, + bool sel = @true, + bool control = @false, + bool shift = @false, + bool alt = @false, + bool meta = @false); + //@} + + /** + Returns @true if the Alt key was down at the time of the event. + */ + bool AltDown(); + + /** + Returns @true if the Control key was down at the time of the event. + */ + bool ControlDown(); + + /** + Top left corner of the rectangular area that was (de)selected. + */ + wxGridCellCoords GetBottomRightCoords(); + + /** + Bottom row of the rectangular area that was (de)selected. + */ + int GetBottomRow(); + + /** + Left column of the rectangular area that was (de)selected. + */ + int GetLeftCol(); + + /** + Right column of the rectangular area that was (de)selected. + */ + int GetRightCol(); + + /** + Top left corner of the rectangular area that was (de)selected. + */ + wxGridCellCoords GetTopLeftCoords(); + + /** + Top row of the rectangular area that was (de)selected. + */ + int GetTopRow(); + + /** + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown(); + + /** + Returns @true if the area was selected, @false otherwise. + */ + bool Selecting(); + + /** + Returns @true if the Shift key was down at the time of the event. + */ + bool ShiftDown(); +}; + + +/** + @class wxGridCellRenderer + @wxheader{grid.h} + + This class is responsible for actually drawing the cell + in the grid. You may pass it to the wxGridCellAttr (below) to change the + format of one given cell or to wxGrid::SetDefaultRenderer() to change the + view of all cells. This is an abstract class, and you will normally use one of + the + predefined derived classes or derive your own class from it. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellStringRenderer, wxGridCellNumberRenderer, wxGridCellFloatRenderer, + wxGridCellBoolRenderer +*/ +class wxGridCellRenderer +{ +public: + /** + + */ + wxGridCellRenderer* Clone(); + + /** + Draw the given cell on the provided DC inside the given rectangle + using the style specified by the attribute and the default or selected + state corresponding to the isSelected value. + + This pure virtual function has a default implementation which will + prepare the DC using the given attribute: it will draw the rectangle + with the background colour from attr and set the text colour and font. + */ + void Draw(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, + const wxRect& rect, int row, int col, + bool isSelected); + + /** + Get the preferred size of the cell for its contents. + */ + wxSize GetBestSize(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, + int row, int col); +}; + + +/** + @class wxGridCellNumberEditor + @wxheader{grid.h} + + The editor for numeric integer data. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, + wxGridCellTextEditor, wxGridCellChoiceEditor +*/ +class wxGridCellNumberEditor : public wxGridCellTextEditor +{ +public: + /** + Allows to specify the range for acceptable data; + if min == max == -1, no range checking is done + */ + wxGridCellNumberEditor(int min = -1, int max = -1); + + /** + String representation of the value. + */ + wxString GetString(); + + /** + If the return value is @true, the editor uses a wxSpinCtrl to get user input, + otherwise it uses a wxTextCtrl. + */ + bool HasRange(); + + /** + Parameters string format is "min,max". + */ + void SetParameters(const wxString& params); +}; + + +/** + @class wxGridSizeEvent + @wxheader{grid.h} + + This event class contains information about a row/column resize event. + + @library{wxadv} + @category{FIXME} +*/ +class wxGridSizeEvent : public wxNotifyEvent +{ +public: + //@{ + /** + + */ + wxGridSizeEvent(); + wxGridSizeEvent(int id, wxEventType type, wxObject* obj, + int rowOrCol = -1, + int x = -1, + int y = -1, + bool control = @false, + bool shift = @false, + bool alt = @false, + bool meta = @false); + //@} + + /** + Returns @true if the Alt key was down at the time of the event. + */ + bool AltDown(); + + /** + Returns @true if the Control key was down at the time of the event. + */ + bool ControlDown(); + + /** + Position in pixels at which the event occurred. + */ + wxPoint GetPosition(); + + /** + Row or column at that was resized. + */ + int GetRowOrCol(); + + /** + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown(); + + /** + Returns @true if the Shift key was down at the time of the event. + */ + bool ShiftDown(); +}; + + +/** + @class wxGridCellNumberRenderer + @wxheader{grid.h} + + This class may be used to format integer data in a cell. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellRenderer, wxGridCellStringRenderer, wxGridCellFloatRenderer, + wxGridCellBoolRenderer +*/ +class wxGridCellNumberRenderer : public wxGridCellStringRenderer +{ +public: + /** + Default constructor + */ + wxGridCellNumberRenderer(); +}; + + +/** + @class wxGridCellAttr + @wxheader{grid.h} + + This class can be used to alter the cells' appearance in + the grid by changing their colour/font/... from default. An object of this + class may be returned by wxGridTableBase::GetAttr. + + @library{wxadv} + @category{FIXME} +*/ +class wxGridCellAttr +{ +public: + //@{ + /** + Constructor specifying some of the often used attributes. + */ + wxGridCellAttr(); + wxGridCellAttr(const wxColour& colText, + const wxColour& colBack, + const wxFont& font, + int hAlign, int vAlign); + //@} + + /** + Creates a new copy of this object. + */ + wxGridCellAttr* Clone(); + + /** + + */ + void DecRef(); + + /** + See SetAlignment() for the returned values. + */ + void GetAlignment(int* hAlign, int* vAlign); + + /** + + */ + const wxColour GetBackgroundColour(); + + /** + + */ + wxGridCellEditor* GetEditor(wxGrid* grid, int row, int col); + + /** + + */ + const wxFont GetFont(); + + /** + + */ + wxGridCellRenderer* GetRenderer(wxGrid* grid, int row, int col); + + /** + + */ + const wxColour GetTextColour(); + + /** + + */ + bool HasAlignment(); + + /** + + */ + bool HasBackgroundColour(); + + /** + + */ + bool HasEditor(); + + /** + + */ + bool HasFont(); + + /** + + */ + bool HasRenderer(); + + /** + accessors + */ + bool HasTextColour(); + + /** + This class is ref counted: it is created with ref count of 1, so + calling DecRef() once will delete it. Calling IncRef() allows to lock + it until the matching DecRef() is called + */ + void IncRef(); + + /** + + */ + bool IsReadOnly(); + + /** + Sets the alignment. @e hAlign can be one of @c wxALIGN_LEFT, + @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @e vAlign can be one + of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. + */ + void SetAlignment(int hAlign, int vAlign); + + /** + Sets the background colour. + */ + void SetBackgroundColour(const wxColour& colBack); + + /** + + */ + void SetDefAttr(wxGridCellAttr* defAttr); + + /** + + */ + void SetEditor(wxGridCellEditor* editor); + + /** + Sets the font. + */ + void SetFont(const wxFont& font); + + /** + + */ + void SetReadOnly(bool isReadOnly = @true); + + /** + takes ownership of the pointer + */ + void SetRenderer(wxGridCellRenderer* renderer); + + /** + Sets the text colour. + */ + void SetTextColour(const wxColour& colText); +}; + + +/** + @class wxGridCellBoolRenderer + @wxheader{grid.h} + + This class may be used to format boolean data in a cell. + for string cells. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellRenderer, wxGridCellStringRenderer, wxGridCellFloatRenderer, + wxGridCellNumberRenderer +*/ +class wxGridCellBoolRenderer : public wxGridCellRenderer +{ +public: + /** + Default constructor + */ + wxGridCellBoolRenderer(); +}; + + +/** + @class wxGridEvent + @wxheader{grid.h} + + This event class contains information about various grid events. + + @library{wxadv} + @category{FIXME} +*/ +class wxGridEvent : public wxNotifyEvent +{ +public: + //@{ + /** + + */ + wxGridEvent(); + wxGridEvent(int id, wxEventType type, wxObject* obj, + int row = -1, int col = -1, + int x = -1, int y = -1, + bool sel = @true, + bool control = @false, + bool shift = @false, + bool alt = @false, + bool meta = @false); + //@} + + /** + Returns @true if the Alt key was down at the time of the event. + */ + bool AltDown(); + + /** + Returns @true if the Control key was down at the time of the event. + */ + bool ControlDown(); + + /** + Column at which the event occurred. + */ + int GetCol(); + + /** + Position in pixels at which the event occurred. + */ + wxPoint GetPosition(); + + /** + Row at which the event occurred. + */ + int GetRow(); + + /** + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown(); + + /** + Returns @true if the user is selecting grid cells, @false -- if + deselecting. + */ + bool Selecting(); + + /** + Returns @true if the Shift key was down at the time of the event. + */ + bool ShiftDown(); +}; + + +/** + @class wxGridCellFloatEditor + @wxheader{grid.h} + + The editor for floating point numbers data. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellEditor, wxGridCellNumberEditor, wxGridCellBoolEditor, + wxGridCellTextEditor, wxGridCellChoiceEditor +*/ +class wxGridCellFloatEditor : public wxGridCellTextEditor +{ +public: + /** + @param width + Minimum number of characters to be shown. + + @param precision + Number of digits after the decimal dot. + */ + wxGridCellFloatEditor(int width = -1, int precision = -1); + + /** + Parameters string format is "width,precision" + */ + void SetParameters(const wxString& params); +}; + + +/** + @class wxGrid + @wxheader{grid.h} + + wxGrid and its related classes are used for displaying and editing tabular + data. They provide a rich set of features for display, editing, and + interacting with a variety of data sources. For simple applications, and to + help you get started, wxGrid is the only class you need to refer to + directly. It will set up default instances of the other classes and manage + them for you. For more complex applications you can derive your own + classes for custom grid views, grid data tables, cell editors and + renderers. The @ref overview_gridoverview "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. The new grid classes are reasonably backward-compatible + but there are some exceptions. There are also easier ways of doing many things + compared to + the previous implementation. + + A wxGridTableBase class holds the actual + data to be displayed by a wxGrid class. One or more wxGrid classes + may act as a view for one table class. + The default table class is called wxGridStringTable and + holds an array of strings. An instance of such a class is created + by wxGrid::CreateGrid. + + wxGridCellRenderer is the abstract base + class for rendereing contents in a cell. The following renderers are + predefined: + wxGridCellStringRenderer, + wxGridCellBoolRenderer, + wxGridCellFloatRenderer, + wxGridCellNumberRenderer. The + look of a cell can be further defined using wxGridCellAttr. + An object of this type may be returned by wxGridTableBase::GetAttr. + + wxGridCellEditor is the abstract base + class for editing the value of a cell. The following editors are + predefined: + wxGridCellTextEditor + wxGridCellBoolEditor + wxGridCellChoiceEditor + wxGridCellNumberEditor. + + @library{wxadv} + @category{miscwnd} + + @seealso + @ref overview_gridoverview "wxGrid overview" +*/ +class wxGrid : public wxScrolledWindow +{ +public: + //@{ + /** + Constructor to create a grid object. Call either CreateGrid() or + SetTable() directly after this to initialize the grid before using + it. + */ + wxGrid(); + wxGrid(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxWANTS_CHARS, + const wxString& name = wxPanelNameStr); + //@} + + /** + Destructor. This will also destroy the associated grid table unless you passed + a table + object to the grid and specified that the grid should not take ownership of the + table (see wxGrid::SetTable). + */ + ~wxGrid(); + + /** + Appends one or more new columns to the right of the grid and returns @true if + successful. The updateLabels argument is not used at present. + + If you are using a derived grid table class you will need to override + wxGridTableBase::AppendCols. See + InsertCols() for further information. + */ + bool AppendCols(int numCols = 1, bool updateLabels = @true); + + /** + Appends one or more new rows to the bottom of the grid and returns @true if + successful. The updateLabels argument is not used at present. + + If you are using a derived grid table class you will need to override + wxGridTableBase::AppendRows. See + InsertRows() for further information. + */ + bool AppendRows(int numRows = 1, bool updateLabels = @true); + + /** + Automatically sets the height and width of all rows and columns to fit their + contents. + */ + void AutoSize(); + + /** + Automatically adjusts width of the column to fit its label. + */ + void AutoSizeColLabelSize(int col); + + /** + Automatically sizes the column to fit its contents. If setAsMin is @true the + calculated width will + also be set as the minimal width for the column. + */ + void AutoSizeColumn(int col, bool setAsMin = @true); + + /** + Automatically sizes all columns to fit their contents. If setAsMin is @true the + calculated widths will + also be set as the minimal widths for the columns. + */ + void AutoSizeColumns(bool setAsMin = @true); + + /** + Automatically sizes the row to fit its contents. If setAsMin is @true the + calculated height will + also be set as the minimal height for the row. + */ + void AutoSizeRow(int row, bool setAsMin = @true); + + /** + Automatically adjusts height of the row to fit its label. + */ + void AutoSizeRowLabelSize(int col); + + /** + Automatically sizes all rows to fit their contents. If setAsMin is @true the + calculated heights will + also be set as the minimal heights for the rows. + */ + void AutoSizeRows(bool setAsMin = @true); + + /** + AutoSizeColumn() + + AutoSizeRow() + + AutoSizeColumns() + + AutoSizeRows() + + AutoSize() + + SetColMinimalWidth() + + SetRowMinimalHeight() + + SetColMinimalAcceptableWidth() + + SetRowMinimalAcceptableHeight() + + GetColMinimalAcceptableWidth() + + GetRowMinimalAcceptableHeight() + */ + + + /** + Increments the grid's batch count. When the count is greater than zero + repainting of + the grid is suppressed. Each call to BeginBatch must be matched by a later call + to + EndBatch(). Code that does a lot of grid + modification can be enclosed between BeginBatch and EndBatch calls to avoid + screen flicker. The final EndBatch will cause the grid to be repainted. + + @sa wxGridUpdateLocker + */ + void BeginBatch(); + + /** + This function returns the rectangle that encloses the block of cells + limited by TopLeft and BottomRight cell in device coords and clipped + to the client size of the grid window. + */ + wxRect BlockToDeviceRect(const wxGridCellCoords & topLeft, + const wxGridCellCoords & bottomRight); + + /** + Returns @true if columns can be moved by dragging with the mouse. Columns can be + moved + by dragging on their labels. + */ + bool CanDragColMove(); + + /** + Returns @true if columns can be resized by dragging with the mouse. Columns can + be resized + by dragging the edges of their labels. If grid line dragging is enabled they + can also be + resized by dragging the right edge of the column in the grid cell area + (see wxGrid::EnableDragGridSize). + */ + bool CanDragColSize(); + + /** + Return @true if the dragging of grid lines to resize rows and columns is enabled + or @false otherwise. + */ + bool CanDragGridSize(); + + /** + Returns @true if rows can be resized by dragging with the mouse. Rows can be + resized + by dragging the edges of their labels. If grid line dragging is enabled they + can also be + resized by dragging the lower edge of the row in the grid cell area + (see wxGrid::EnableDragGridSize). + */ + bool CanDragRowSize(); + + /** + Returns @true if the in-place edit control for the current grid cell can be used + and + @false otherwise (e.g. if the current cell is read-only). + */ + bool CanEnableCellControl(); + + /** + Do we have some place to store attributes in? + */ + bool CanHaveAttributes(); + + /** + EnableDragRowSize() + + EnableDragColSize() + + CanDragRowSize() + + CanDragColSize() + + EnableDragColMove() + + CanDragColMove() + + EnableDragGridSize() + + CanDragGridSize() + + GetColAt() + + SetColPos() + + GetColPos() + + EnableDragCell() + + CanDragCell() + */ + + + //@{ + /** + Return the rectangle corresponding to the grid cell's size and position in + logical + coordinates. + */ + wxRect CellToRect(int row, int col); + wxRect CellToRect(const wxGridCellCoords& coords); + //@} + + /** + Clears all data in the underlying grid table and repaints the grid. The table + is not deleted by + this function. If you are using a derived table class then you need to override + wxGridTableBase::Clear for this function to have any effect. + */ + void ClearGrid(); + + /** + Deselects all cells that are currently selected. + */ + void ClearSelection(); + + /** + @ref ctor() wxGrid + + @ref dtor() ~wxGrid + + CreateGrid() + + SetTable() + */ + + + /** + Creates a grid with the specified initial number of rows and columns. + Call this directly after the grid constructor. When you use this + function wxGrid will create and manage a simple table of string values + for you. All of the grid data will be stored in memory. + + For applications with more complex data types or relationships, or for + dealing with very large datasets, you should derive your own grid table + class and pass a table object to the grid with SetTable(). + */ + bool CreateGrid(int numRows, int numCols, + wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); + + /** + MoveCursorUp() + + MoveCursorDown() + + MoveCursorLeft() + + MoveCursorRight() + + MoveCursorPageUp() + + MoveCursorPageDown() + + MoveCursorUpBlock() + + MoveCursorDownBlock() + + MoveCursorLeftBlock() + + MoveCursorRightBlock() + */ + + + /** + Deletes one or more columns from a grid starting at the specified position and + returns + @true if successful. The updateLabels argument is not used at present. + + If you are using a derived grid table class you will need to override + wxGridTableBase::DeleteCols. See + InsertCols() for further information. + */ + bool DeleteCols(int pos = 0, int numCols = 1, + bool updateLabels = @true); + + /** + Deletes one or more rows from a grid starting at the specified position and + returns + @true if successful. The updateLabels argument is not used at present. + + If you are using a derived grid table class you will need to override + wxGridTableBase::DeleteRows. See + InsertRows() for further information. + */ + bool DeleteRows(int pos = 0, int numRows = 1, + bool updateLabels = @true); + + /** + Disables in-place editing of grid cells. + Equivalent to calling EnableCellEditControl(@false). + */ + void DisableCellEditControl(); + + /** + Disables column moving by dragging with the mouse. Equivalent to passing @false + to + EnableDragColMove(). + */ + void DisableDragColMove(); + + /** + Disables column sizing by dragging with the mouse. Equivalent to passing @false + to + EnableDragColSize(). + */ + void DisableDragColSize(); + + /** + Disable mouse dragging of grid lines to resize rows and columns. Equivalent to + passing + @false to EnableDragGridSize() + */ + void DisableDragGridSize(); + + /** + Disables row sizing by dragging with the mouse. Equivalent to passing @false to + EnableDragRowSize(). + */ + void DisableDragRowSize(); + + /** + Enables or disables in-place editing of grid cell data. The grid will issue + either a + wxEVT_GRID_EDITOR_SHOWN or wxEVT_GRID_EDITOR_HIDDEN event. + */ + void EnableCellEditControl(bool enable = @true); + + /** + Enables or disables column moving by dragging with the mouse. + */ + void EnableDragColMove(bool enable = @true); + + /** + Enables or disables column sizing by dragging with the mouse. + */ + void EnableDragColSize(bool enable = @true); + + /** + Enables or disables row and column resizing by dragging gridlines with the + mouse. + */ + void EnableDragGridSize(bool enable = @true); + + /** + Enables or disables row sizing by dragging with the mouse. + */ + void EnableDragRowSize(bool enable = @true); + + /** + If the edit argument is @false this function sets the whole grid as read-only. + If the + argument is @true the grid is set to the default state where cells may be + editable. In the + default state you can set single grid cells and whole rows and columns to be + editable or + read-only via + wxGridCellAttribute::SetReadOnly. For single + cells you can also use the shortcut function + SetReadOnly(). + + For more information about controlling grid cell attributes see the + wxGridCellAttr cell attribute class and the + @ref overview_gridoverview "wxGrid classes overview". + */ + void EnableEditing(bool edit); + + /** + Turns the drawing of grid lines on or off. + */ + void EnableGridLines(bool enable = @true); + + /** + Decrements the grid's batch count. When the count is greater than zero + repainting of + the grid is suppressed. Each previous call to + BeginBatch() must be matched by a later call to + EndBatch. Code that does a lot of grid modification can be enclosed between + BeginBatch and EndBatch calls to avoid screen flicker. The final EndBatch will + cause the grid to be repainted. + + @sa wxGridUpdateLocker + */ + void EndBatch(); + + /** + Overridden wxWindow method. + */ +#define void Fit() /* implementation is private */ + + /** + Causes immediate repainting of the grid. Use this instead of the usual + wxWindow::Refresh. + */ + void ForceRefresh(); + + /** + Returns the number of times that BeginBatch() has been called + without (yet) matching calls to EndBatch(). While + the grid's batch count is greater than zero the display will not be updated. + */ + int GetBatchCount(); + + /** + Sets the arguments to the horizontal and vertical text alignment values for the + grid cell at the specified location. + + Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + */ + void GetCellAlignment(int row, int col, int* horiz, int* vert); + + /** + Returns the background colour of the cell at the specified location. + */ + wxColour GetCellBackgroundColour(int row, int col); + + /** + Returns a pointer to the editor for the cell at the specified location. + + See wxGridCellEditor and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + wxGridCellEditor* GetCellEditor(int row, int col); + + /** + Returns the font for text in the grid cell at the specified location. + */ + wxFont GetCellFont(int row, int col); + + /** + Returns a pointer to the renderer for the grid cell at the specified location. + + See wxGridCellRenderer and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + wxGridCellRenderer* GetCellRenderer(int row, int col); + + /** + Returns the text colour for the grid cell at the specified location. + */ + wxColour GetCellTextColour(int row, int col); + + //@{ + /** + Returns the string contained in the cell at the specified location. For simple + applications where a + grid object automatically uses a default grid table of string values you use + this function together + with SetCellValue() to access cell values. + + For more complex applications where you have derived your own grid table class + that contains + various data types (e.g. numeric, boolean or user-defined custom types) then + you only use this + function for those cells that contain string values. + + See wxGridTableBase::CanGetValueAs + and the @ref overview_gridoverview "wxGrid overview" for more information. + */ + wxString GetCellValue(int row, int col); + wxString GetCellValue(const wxGridCellCoords& coords); + //@} + + /** + Returns the column ID of the specified column position. + */ + int GetColAt(int colPos); + + /** + Returns the pen used for vertical grid lines. This virtual function may be + overridden in derived classes in order to change the appearance of individual + grid lines for the given column @e col. + + See GetRowGridLinePen() for an example. + */ + wxPen GetColGridLinePen(int col); + + /** + Sets the arguments to the current column label alignment values. + + Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + */ + void GetColLabelAlignment(int* horiz, int* vert); + + /** + Returns the current height of the column labels. + */ + int GetColLabelSize(); + + /** + Returns the specified column label. The default grid table class provides + column labels of + the form A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can + override + wxGridTableBase::GetColLabelValue to provide + your own labels. + */ + wxString GetColLabelValue(int col); + + /** + + */ + int GetColLeft(int col); + + /** + This returns the value of the lowest column width that can be handled + correctly. See + member SetColMinimalAcceptableWidth() for details. + */ + int GetColMinimalAcceptableWidth(); + + /** + Get the minimal width of the given column/row. + */ + int GetColMinimalWidth(int col); + + /** + Returns the position of the specified column. + */ + int GetColPos(int colID); + + /** + + */ + int GetColRight(int col); + + /** + Returns the width of the specified column. + */ + int GetColSize(int col); + + /** + Sets the arguments to the current default horizontal and vertical text alignment + values. + + Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + */ + void GetDefaultCellAlignment(int* horiz, int* vert); + + /** + Returns the current default background colour for grid cells. + */ + wxColour GetDefaultCellBackgroundColour(); + + /** + Returns the current default font for grid cell text. + */ + wxFont GetDefaultCellFont(); + + /** + Returns the current default colour for grid cell text. + */ + wxColour GetDefaultCellTextColour(); + + /** + Returns the default height for column labels. + */ + int GetDefaultColLabelSize(); + + /** + Returns the current default width for grid columns. + */ + int GetDefaultColSize(); + + /** + Returns a pointer to the current default grid cell editor. + + See wxGridCellEditor and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + wxGridCellEditor* GetDefaultEditor(); + + //@{ + /** + + */ + wxGridCellEditor* GetDefaultEditorForCell(int row, int col); + wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c); + //@} + + /** + + */ + wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName); + + /** + Returns the pen used for grid lines. This virtual function may be overridden in + derived classes in order to change the appearance of grid lines. Note that + currently the pen width must be 1. + + @sa GetColGridLinePen(), GetRowGridLinePen() + */ + wxPen GetDefaultGridLinePen(); + + /** + Returns a pointer to the current default grid cell renderer. + + See wxGridCellRenderer and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + wxGridCellRenderer* GetDefaultRenderer(); + + /** + + */ + wxGridCellRenderer* GetDefaultRendererForCell(int row, int col); + + /** + + */ + wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName); + + /** + Returns the default width for the row labels. + */ + int GetDefaultRowLabelSize(); + + /** + Returns the current default height for grid rows. + */ + int GetDefaultRowSize(); + + /** + Returns the current grid cell column position. + */ + int GetGridCursorCol(); + + /** + Returns the current grid cell row position. + */ + int GetGridCursorRow(); + + /** + Returns the colour used for grid lines. + + @sa GetDefaultGridLinePen() + */ + wxColour GetGridLineColour(); + + /** + Returns the colour used for the background of row and column labels. + */ + wxColour GetLabelBackgroundColour(); + + /** + Returns the font used for row and column labels. + */ + wxFont GetLabelFont(); + + /** + Returns the colour used for row and column label text. + */ + wxColour GetLabelTextColour(); + + /** + Returns the total number of grid columns (actually the number of columns in the + underlying grid + table). + */ + int GetNumberCols(); + + /** + Returns the total number of grid rows (actually the number of rows in the + underlying grid table). + */ + int GetNumberRows(); + + /** + + */ + wxGridCellAttr* GetOrCreateCellAttr(int row, int col); + + /** + Returns the pen used for horizontal grid lines. This virtual function may be + overridden in derived classes in order to change the appearance of individual + grid line for the given row @e row. + + Example: + */ + wxPen GetRowGridLinePen(int row); + + /** + Sets the arguments to the current row label alignment values. + + Horizontal alignment will be one of wxLEFT, wxCENTRE or wxRIGHT. + + Vertical alignment will be one of wxTOP, wxCENTRE or wxBOTTOM. + */ + void GetRowLabelAlignment(int* horiz, int* vert); + + /** + Returns the current width of the row labels. + */ + int GetRowLabelSize(); + + /** + Returns the specified row label. The default grid table class provides numeric + row labels. + If you are using a custom grid table you can override + wxGridTableBase::GetRowLabelValue to provide + your own labels. + */ + wxString GetRowLabelValue(int row); + + /** + This returns the value of the lowest row width that can be handled correctly. + See + member SetRowMinimalAcceptableHeight() for details. + */ + int GetRowMinimalAcceptableHeight(); + + /** + + */ + int GetRowMinimalHeight(int col); + + /** + Returns the height of the specified row. + */ + int GetRowSize(int row); + + /** + Returns the number of pixels per horizontal scroll increment. The default is 15. + + @sa GetScrollLineY(), SetScrollLineX(), SetScrollLineY() + */ + int GetScrollLineX(); + + /** + Returns the number of pixels per vertical scroll increment. The default is 15. + + @sa GetScrollLineX(), SetScrollLineX(), SetScrollLineY() + */ + int GetScrollLineY(); + + /** + Returns an array of singly selected cells. + */ + wxGridCellCoordsArray GetSelectedCells(); + + /** + Returns an array of selected cols. + */ + wxArrayInt GetSelectedCols(); + + /** + Returns an array of selected rows. + */ + wxArrayInt GetSelectedRows(); + + /** + Access or update the selection fore/back colours + */ + wxColour GetSelectionBackground(); + + /** + Returns an array of the bottom right corners of blocks of selected cells, + see GetSelectionBlockTopLeft(). + */ + wxGridCellCoordsArray GetSelectionBlockBottomRight(); + + /** + Returns an array of the top left corners of blocks of selected cells, + see GetSelectionBlockBottomRight(). + */ + wxGridCellCoordsArray GetSelectionBlockTopLeft(); + + /** + + */ + wxColour GetSelectionForeground(); + + /** + Returns the current selection mode, see SetSelectionMode(). + */ + wxGrid::wxGridSelectionModes GetSelectionMode(); + + /** + Returns a base pointer to the current table object. + */ + wxGridTableBase * GetTable(); + + /** + Returned number of whole cols visible. + */ + int GetViewWidth(); + + /** + EnableGridLines() + + GridLinesEnabled() + + SetGridLineColour() + + GetGridLineColour() + + GetDefaultGridLinePen() + + GetRowGridLinePen() + + GetColGridLinePen() + */ + + + /** + Returns @true if drawing of grid lines is turned on, @false otherwise. + */ + bool GridLinesEnabled(); + + /** + Hides the in-place cell edit control. + */ + void HideCellEditControl(); + + /** + Hides the column labels by calling SetColLabelSize() + with a size of 0. Show labels again by calling that method with + a width greater than 0. + */ + void HideColLabels(); + + /** + Hides the row labels by calling SetRowLabelSize() + with a size of 0. Show labels again by calling that method with + a width greater than 0. + */ + void HideRowLabels(); + + /** + Init the m_colWidths/Rights arrays + */ + void InitColWidths(); + + /** + NB: @e never access m_row/col arrays directly because they are created + on demand, @e always use accessor functions instead! + + Init the m_rowHeights/Bottoms arrays with default values. + */ + void InitRowHeights(); + + /** + Inserts one or more new columns into a grid with the first new column at the + specified position and returns @true if successful. The updateLabels argument is + not + used at present. + + The sequence of actions begins with the grid object requesting the underlying + grid + table to insert new columns. If this is successful the table notifies the grid + and the + grid updates the display. For a default grid (one where you have called + wxGrid::CreateGrid) this process is automatic. If you are + using a custom grid table (specified with wxGrid::SetTable) + then you must override + wxGridTableBase::InsertCols in your derived + table class. + */ + bool InsertCols(int pos = 0, int numCols = 1, + bool updateLabels = @true); + + /** + Inserts one or more new rows into a grid with the first new row at the specified + position and returns @true if successful. The updateLabels argument is not used + at + present. + + The sequence of actions begins with the grid object requesting the underlying + grid + table to insert new rows. If this is successful the table notifies the grid and + the + grid updates the display. For a default grid (one where you have called + wxGrid::CreateGrid) this process is automatic. If you are + using a custom grid table (specified with wxGrid::SetTable) + then you must override + wxGridTableBase::InsertRows in your derived + table class. + */ + bool InsertRows(int pos = 0, int numRows = 1, + bool updateLabels = @true); + + /** + Returns @true if the in-place edit control is currently enabled. + */ + bool IsCellEditControlEnabled(); + + /** + Returns @true if the current cell has been set to read-only + (see wxGrid::SetReadOnly). + */ + bool IsCurrentCellReadOnly(); + + /** + Returns @false if the whole grid has been set as read-only or @true otherwise. + See EnableEditing() for more information about + controlling the editing status of grid cells. + */ + bool IsEditable(); + + //@{ + /** + Is this cell currently selected. + */ + bool IsInSelection(int row, int col); + bool IsInSelection(const wxGridCellCoords& coords); + //@} + + /** + Returns @true if the cell at the specified location can't be edited. + See also IsReadOnly(). + */ + bool IsReadOnly(int row, int col); + + /** + Returns @true if there are currently rows, columns or blocks of cells selected. + */ + bool IsSelection(); + + //@{ + /** + Returns @true if a cell is either wholly visible (the default) or at least + partially + visible in the grid window. + */ + bool IsVisible(int row, int col, bool wholeCellVisible = @true); + bool IsVisible(const wxGridCellCoords& coords, + bool wholeCellVisible = @true); + //@} + + //@{ + /** + Brings the specified cell into the visible grid cell area with minimal + scrolling. Does + nothing if the cell is already visible. + */ + void MakeCellVisible(int row, int col); + void MakeCellVisible(const wxGridCellCoords& coords); + //@} + + /** + Moves the grid cursor down by one row. If a block of cells was previously + selected it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorDown(bool expandSelection); + + /** + Moves the grid cursor down in the current column such that it skips to the + beginning or + end of a block of non-empty cells. If a block of cells was previously selected + it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorDownBlock(bool expandSelection); + + /** + Moves the grid cursor left by one column. If a block of cells was previously + selected it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorLeft(bool expandSelection); + + /** + Moves the grid cursor left in the current row such that it skips to the + beginning or + end of a block of non-empty cells. If a block of cells was previously selected + it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorLeftBlock(bool expandSelection); + + /** + Moves the grid cursor right by one column. If a block of cells was previously + selected it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorRight(bool expandSelection); + + /** + Moves the grid cursor right in the current row such that it skips to the + beginning or + end of a block of non-empty cells. If a block of cells was previously selected + it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorRightBlock(bool expandSelection); + + /** + Moves the grid cursor up by one row. If a block of cells was previously + selected it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorUp(bool expandSelection); + + /** + Moves the grid cursor up in the current column such that it skips to the + beginning or + end of a block of non-empty cells. If a block of cells was previously selected + it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorUpBlock(bool expandSelection); + + /** + Moves the grid cursor down by some number of rows so that the previous bottom + visible row + becomes the top visible row. + */ + bool MovePageDown(); + + /** + Moves the grid cursor up by some number of rows so that the previous top + visible row + becomes the bottom visible row. + */ + bool MovePageUp(); + + /** + Methods for a registry for mapping data types to Renderers/Editors + */ + void RegisterDataType(const wxString& typeName, + wxGridCellRenderer* renderer, + wxGridCellEditor* editor); + + /** + SetRowLabelValue() + + SetColLabelValue() + + GetRowLabelValue() + + GetColLabelValue() + + SetUseNativeColLabels() + + HideColLabels() + + HideRowLabels() + + SetRowLabelSize() + + SetColLabelSize() + + GetRowLabelSize() + + GetColLabelSize() + + AutoSizeRowLabelSize() + + AutoSizeColLabelSize() + + GetDefaultRowLabelSize() + + GetDefaultColLabelSize() + + SetRowLabelAlignment() + + SetColLabelAlignment() + + GetRowLabelAlignment() + + GetColLabelAlignment() + + SetLabelFont() + + SetLabelTextColour() + + SetLabelBackgroundColour() + + GetLabelFont() + + GetLabelBackgroundColour() + + GetLabelTextColour() + + SetColLabelTextOrientation() + + GetColLabelTextOrientation() + */ + + + /** + Sets the value of the current grid cell to the current in-place edit control + value. + This is called automatically when the grid cursor moves from the current cell + to a + new cell. It is also a good idea to call this function when closing a grid since + any edits to the final cell location will not be saved otherwise. + */ + void SaveEditControlValue(); + + /** + Selects all cells in the grid. + */ + void SelectAll(); + + //@{ + /** + Selects a rectangular block of cells. If addToSelected is @false then any + existing selection will be + deselected; if @true the column will be added to the existing selection. + */ + void SelectBlock(int topRow, int leftCol, int bottomRow, + int rightCol, + bool addToSelected = @false); + void SelectBlock(const wxGridCellCoords& topLeft, + const wxGridCellCoords& bottomRight, + bool addToSelected = @false); + //@} + + /** + Selects the specified column. If addToSelected is @false then any existing + selection will be + deselected; if @true the column will be added to the existing selection. + */ + void SelectCol(int col, bool addToSelected = @false); + + /** + Selects the specified row. If addToSelected is @false then any existing + selection will be + deselected; if @true the row will be added to the existing selection. + */ + void SelectRow(int row, bool addToSelected = @false); + + /** + ClearSelection() + + IsSelection() + + SelectAll() + + SelectBlock() + + SelectCol() + + SelectRow() + */ + + + /** + This function returns the rectangle that encloses the selected cells + in device coords and clipped to the client size of the grid window. + */ + wxRect SelectionToDeviceRect(); + + //@{ + /** + Sets the horizontal and vertical alignment for grid cell text at the specified + location. + + Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or + wxALIGN_BOTTOM. + */ + void SetCellAlignment(int row, int col, int horiz, int vert); + void SetCellAlignment(int align, int row, int col); + //@} + + /** + + */ + void SetCellBackgroundColour(int row, int col, + const wxColour& colour); + + /** + Sets the editor for the grid cell at the specified location. + The grid will take ownership of the pointer. + + See wxGridCellEditor and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + void SetCellEditor(int row, int col, wxGridCellEditor* editor); + + /** + Sets the font for text in the grid cell at the specified location. + */ + void SetCellFont(int row, int col, const wxFont& font); + + /** + Sets the renderer for the grid cell at the specified location. + The grid will take ownership of the pointer. + + See wxGridCellRenderer and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + void SetCellRenderer(int row, int col, + wxGridCellRenderer* renderer); + + //@{ + /** + Sets the text colour for the grid cell at the specified location. + */ + void SetCellTextColour(int row, int col, const wxColour& colour); + void SetCellTextColour(const wxColour& val, int row, int col); + void SetCellTextColour(const wxColour& colour); + //@} + + //@{ + /** + Sets the string value for the cell at the specified location. For simple + applications where a + grid object automatically uses a default grid table of string values you use + this function together + with GetCellValue() to access cell values. + + For more complex applications where you have derived your own grid table class + that contains + various data types (e.g. numeric, boolean or user-defined custom types) then + you only use this + function for those cells that contain string values. + + The last form is for backward compatibility only. + + See wxGridTableBase::CanSetValueAs + and the @ref overview_gridoverview "wxGrid overview" for more information. + */ + void SetCellValue(int row, int col, const wxString& s); + void SetCellValue(const wxGridCellCoords& coords, + const wxString& s); + void SetCellValue(const wxString& val, int row, int col); + //@} + + /** + Sets the cell attributes for all cells in the specified column. + + For more information about controlling grid cell attributes see the + wxGridCellAttr cell attribute class and the + @ref overview_gridoverview "wxGrid classes overview". + */ + void SetColAttr(int col, wxGridCellAttr* attr); + + /** + Sets the specified column to display boolean values. wxGrid displays boolean + values with a checkbox. + */ + void SetColFormatBool(int col); + + /** + Sets the specified column to display data in a custom format. + See the @ref overview_gridoverview "wxGrid overview" for more information on + working + with custom data types. + */ + void SetColFormatCustom(int col, const wxString& typeName); + + /** + Sets the specified column to display floating point values with the given width + and precision. + */ + void SetColFormatFloat(int col, int width = -1, + int precision = -1); + + /** + Sets the specified column to display integer values. + */ + void SetColFormatNumber(int col); + + /** + Sets the horizontal and vertical alignment of column label text. + + Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or + wxALIGN_BOTTOM. + */ + void SetColLabelAlignment(int horiz, int vert); + + /** + Sets the height of the column labels. + + If @e height equals to @c wxGRID_AUTOSIZE then height is calculated + automatically + so that no label is truncated. Note that this could be slow for a large table. + */ + void SetColLabelSize(int height); + + /** + Set the value for the given column label. If you are using a derived grid table + you must + override wxGridTableBase::SetColLabelValue + for this to have any effect. + */ + void SetColLabelValue(int col, const wxString& value); + + /** + This modifies the minimum column width that can be handled correctly. + Specifying a low value here + allows smaller grid cells to be dealt with correctly. Specifying a value here + which is much smaller + than the actual minimum size will incur a performance penalty in the functions + which perform + grid cell index lookup on the basis of screen coordinates. + This should normally be called when creating the grid because it will not + resize existing columns + with sizes smaller than the value specified here. + */ + void SetColMinimalAcceptableWidth(int width); + + /** + Sets the minimal width for the specified column. This should normally be called + when creating the grid + because it will not resize a column that is already narrower than the minimal + width. + The width argument must be higher than the minimimal acceptable column width, + see + GetColMinimalAcceptableWidth(). + */ + void SetColMinimalWidth(int col, int width); + + /** + Sets the position of the specified column. + */ + void SetColPos(int colID, int newPos); + + /** + Sets the width of the specified column. + + This function does not refresh the grid. If you are calling it outside of a + BeginBatch / EndBatch + block you can use ForceRefresh() to see the changes. + + Automatically sizes the column to fit its contents. If setAsMin is @true the + calculated width will + also be set as the minimal width for the column. + */ + void SetColSize(int col, int width); + + /** + Sets the default horizontal and vertical alignment for grid cell text. + + Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or + wxALIGN_BOTTOM. + */ + void SetDefaultCellAlignment(int horiz, int vert); + + /** + Sets the default background colour for grid cells. + */ + void SetDefaultCellBackgroundColour(const wxColour& colour); + + /** + Sets the default font to be used for grid cell text. + */ + void SetDefaultCellFont(const wxFont& font); + + /** + Sets the current default colour for grid cell text. + */ + void SetDefaultCellTextColour(const wxColour& colour); + + /** + Sets the default width for columns in the grid. This will only affect columns + subsequently added to + the grid unless resizeExistingCols is @true. + */ + void SetDefaultColSize(int width, + bool resizeExistingCols = @false); + + /** + Sets the default editor for grid cells. The grid will take ownership of the + pointer. + + See wxGridCellEditor and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + void SetDefaultEditor(wxGridCellEditor* editor); + + /** + Sets the default renderer for grid cells. The grid will take ownership of the + pointer. + + See wxGridCellRenderer and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + void SetDefaultRenderer(wxGridCellRenderer* renderer); + + /** + Sets the default height for rows in the grid. This will only affect rows + subsequently added + to the grid unless resizeExistingRows is @true. + */ + void SetDefaultRowSize(int height, + bool resizeExistingRows = @false); + + /** + Set the grid cursor to the specified cell. + This function calls MakeCellVisible(). + */ + void SetGridCursor(int row, int col); + + /** + Sets the colour used to draw grid lines. + */ + void SetGridLineColour(const wxColour& colour); + + /** + Sets the background colour for row and column labels. + */ + void SetLabelBackgroundColour(const wxColour& colour); + + /** + Sets the font for row and column labels. + */ + void SetLabelFont(const wxFont& font); + + /** + Sets the colour for row and column label text. + */ + void SetLabelTextColour(const wxColour& colour); + + /** + A grid may occupy more space than needed for its rows/columns. This + function allows to set how big this extra space is + */ + void SetMargins(int extraWidth, int extraHeight); + + /** + Common part of AutoSizeColumn/Row() and GetBestSize() + */ + int SetOrCalcColumnSizes(bool calcOnly, bool setAsMin = @true); + + /** + + */ + int SetOrCalcRowSizes(bool calcOnly, bool setAsMin = @true); + + /** + Makes the cell at the specified location read-only or editable. + See also IsReadOnly(). + */ + void SetReadOnly(int row, int col, bool isReadOnly = @true); + + /** + Sets the cell attributes for all cells in the specified row. + See the wxGridCellAttr class for more information + about controlling cell attributes. + */ + void SetRowAttr(int row, wxGridCellAttr* attr); + + /** + Sets the horizontal and vertical alignment of row label text. + + Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or + wxALIGN_BOTTOM. + */ + void SetRowLabelAlignment(int horiz, int vert); + + /** + Sets the width of the row labels. + + If @e width equals @c wxGRID_AUTOSIZE then width is calculated automatically + so that no label is truncated. Note that this could be slow for a large table. + */ + void SetRowLabelSize(int width); + + /** + Set the value for the given row label. If you are using a derived grid table + you must + override wxGridTableBase::SetRowLabelValue + for this to have any effect. + */ + void SetRowLabelValue(int row, const wxString& value); + + /** + This modifies the minimum row width that can be handled correctly. Specifying a + low value here + allows smaller grid cells to be dealt with correctly. Specifying a value here + which is much smaller + than the actual minimum size will incur a performance penalty in the functions + which perform + grid cell index lookup on the basis of screen coordinates. + This should normally be called when creating the grid because it will not + resize existing rows + with sizes smaller than the value specified here. + */ + void SetRowMinimalAcceptableHeight(int height); + + /** + Sets the minimal height for the specified row. This should normally be called + when creating the grid + because it will not resize a row that is already shorter than the minimal + height. + The height argument must be higher than the minimimal acceptable row height, see + GetRowMinimalAcceptableHeight(). + */ + void SetRowMinimalHeight(int row, int height); + + /** + Sets the height of the specified row. + + This function does not refresh the grid. If you are calling it outside of a + BeginBatch / EndBatch + block you can use ForceRefresh() to see the changes. + + Automatically sizes the column to fit its contents. If setAsMin is @true the + calculated width will + also be set as the minimal width for the column. + */ + void SetRowSize(int row, int height); + + /** + Sets the number of pixels per horizontal scroll increment. The default is 15. + Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding + errors: setting this to 1 can help. + + @sa GetScrollLineX(), GetScrollLineY(), SetScrollLineY() + */ + void SetScrollLineX(int x); + + /** + Sets the number of pixels per vertical scroll increment. The default is 15. + Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding + errors: setting this to 1 can help. + + @sa GetScrollLineX(), GetScrollLineY(), SetScrollLineX() + */ + void SetScrollLineY(int y); + + /** + + */ + void SetSelectionBackground(const wxColour& c); + + /** + + */ + void SetSelectionForeground(const wxColour& c); + + /** + Set the selection behaviour of the grid. + + @param wxGridSelectCells() + The default mode where individual cells are selected. + + @param wxGridSelectRows() + Selections will consist of whole rows. + + @param wxGridSelectColumns() + Selections will consist of whole columns. + */ + void SetSelectionMode(wxGrid::wxGridSelectionModes selmode); + + /** + Passes a pointer to a custom grid table to be used by the grid. This should be + called + after the grid constructor and before using the grid object. If takeOwnership + is set to + @true then the table will be deleted by the wxGrid destructor. + + Use this function instead of CreateGrid() when your + application involves complex or non-string data or data sets that are too large + to fit + wholly in memory. + */ + bool SetTable(wxGridTableBase* table, bool takeOwnership = @false, + wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); + + /** + Call this in order to make the column labels use a native look by using + wxRenderer::DrawHeaderButton + internally. There is no equivalent method for drawing row columns as + there is not native look for that. This option is useful when using + wxGrid for displaying tables and not as a spread-sheet. + */ + void SetUseNativeColLabels(bool native= @true); + + /** + Displays the in-place cell edit control for the current cell. + */ + void ShowCellEditControl(); + + /** + @param x + The x position to evaluate. + + @param clipToMinMax + If @true, rather than returning wxNOT_FOUND, it returns either the first or last + column depending on whether x is too far to the left or right respectively. + */ + int XToCol(int x, bool clipToMinMax = @false); + + /** + Returns the column whose right hand edge is close to the given logical x + position. + If no column edge is near to this position @c wxNOT_FOUND is returned. + */ + int XToEdgeOfCol(int x); + + /** + Returns the row whose bottom edge is close to the given logical y position. + If no row edge is near to this position @c wxNOT_FOUND is returned. + */ + int YToEdgeOfRow(int y); + + /** + Returns the grid row that corresponds to the logical y coordinate. Returns + @c wxNOT_FOUND if there is no row at the y position. + */ + int YToRow(int y); +}; + + +/** + @class wxGridCellBoolEditor + @wxheader{grid.h} + + The editor for boolean data. + + @library{wxadv} + @category{FIXME} + + @seealso + wxGridCellEditor, wxGridCellFloatEditor, wxGridCellNumberEditor, + wxGridCellTextEditor, wxGridCellChoiceEditor +*/ +class wxGridCellBoolEditor : public wxGridCellEditor +{ +public: + /** + Default constructor. + */ + wxGridCellBoolEditor(); + + /** + Returns @true if the given @e value is equal to the string representation of + the truth value we currently use (see + wxGridCellBoolEditor::UseStringValues). + */ + static bool IsTrueValue(const wxString& value); + + /** + , @b const wxString&@e valueFalse = _T("")) + + This method allows to customize the values returned by GetValue() method for + the cell using this editor. By default, the default values of the arguments are + used, i.e. @c "1" is returned if the cell is checked and an empty string + otherwise, using this method allows to change this. + */ + static void UseStringValues(); +}; + + +/** + @class wxGridUpdateLocker + @wxheader{grid.h} + + This small class can be used to prevent wxGrid from redrawing + during its lifetime by calling wxGrid::BeginBatch + in its constructor and wxGrid::EndBatch in its + destructor. It is typically used in a function performing several operations + with a grid which would otherwise result in flicker. For example: + + @code + void MyFrame::Foo() + { + m_grid = new wxGrid(this, ...); + + wxGridUpdateLocker noUpdates(m_grid); + m_grid-AppendColumn(); + ... many other operations with m_grid... + m_grid-AppendRow(); + + // destructor called, grid refreshed + } + @endcode + + Using this class is easier and safer than calling + wxGrid::BeginBatch and wxGrid::EndBatch + because you don't risk not to call the latter (due to an exception for example). + + @library{wxadv} + @category{FIXME} +*/ +class wxGridUpdateLocker +{ +public: + /** + Creates an object preventing the updates of the specified @e grid. The + parameter could be @NULL in which case nothing is done. If @e grid is + non-@NULL then the grid must exist for longer than wxGridUpdateLocker object + itself. + + The default constructor could be followed by a call to + Create() to set the + grid object later. + */ + wxGridUpdateLocker(wxGrid * grid = @NULL); + + /** + Destructor reenables updates for the grid this object is associated with. + */ + ~wxGridUpdateLocker(); + + /** + This method can be called if the object had been constructed using the default + constructor. It must not be called more than once. + */ + void Create(wxGrid* grid); +}; diff --git a/interface/hash.h b/interface/hash.h new file mode 100644 index 0000000000..581f46013c --- /dev/null +++ b/interface/hash.h @@ -0,0 +1,107 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: hash.h +// Purpose: documentation for wxHashTable class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHashTable + @wxheader{hash.h} + + @b Please note that this class is retained for backward compatibility + reasons; you should use wxHashMap. + + This class provides hash table functionality for wxWidgets, and for an + application if it wishes. Data can be hashed on an integer or string + key. + + @library{wxbase} + @category{containers} + + @seealso + wxList +*/ +class wxHashTable : public wxObject +{ +public: + /** + Constructor. @e key_type is one of wxKEY_INTEGER, or wxKEY_STRING, + and indicates what sort of keying is required. @e size is optional. + */ + wxHashTable(unsigned int key_type, int size = 1000); + + /** + Destroys the hash table. + */ + ~wxHashTable(); + + /** + The counterpart of @e Next. If the application wishes to iterate + through all the data in the hash table, it can call @e BeginFind and + then loop on @e Next. + */ + void BeginFind(); + + /** + Clears the hash table of all nodes (but as usual, doesn't delete user data). + */ + void Clear(); + + //@{ + /** + Deletes entry in hash table and returns the user's data (if found). + */ + wxObject * Delete(long key); + wxObject * Delete(const wxString& key); + //@} + + /** + If set to @true data stored in hash table will be deleted when hash table object + is destroyed. + */ + void DeleteContents(bool flag); + + //@{ + /** + Gets data from the hash table, using an integer or string key (depending on + which + has table constructor was used). + */ + wxObject * Get(long key); + wxObject * Get(const char* key); + //@} + + /** + Returns the number of elements in the hash table. + */ + size_t GetCount(); + + /** + Makes an integer key out of a string. An application may wish to make a key + explicitly (for instance when combining two data values to form a key). + */ + long MakeKey(const wxString& string); + + /** + If the application wishes to iterate through all the data in the hash + table, it can call @e BeginFind and then loop on @e Next. This function + returns a @b Node() pointer (or @NULL if there are no more nodes). + The return value is functionally equivalent to @b wxNode but might not be + implemented as a @b wxNode. The user will probably only wish to use the + @b GetData method to retrieve the data; the node may also be deleted. + */ + wxHashTable::Node * Next(); + + //@{ + /** + Inserts data into the hash table, using an integer or string key (depending on + which + has table constructor was used). The key string is copied and stored by the hash + table implementation. + */ + void Put(long key, wxObject * object); + void Put(const char* key, wxObject * object); + //@} +}; diff --git a/interface/hashmap.h b/interface/hashmap.h new file mode 100644 index 0000000000..cd792f51c0 --- /dev/null +++ b/interface/hashmap.h @@ -0,0 +1,105 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: hashmap.h +// Purpose: documentation for wxHashMap class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHashMap + @wxheader{hashmap.h} + + This is a simple, type-safe, and reasonably efficient hash map class, + whose interface is a subset of the interface of STL containers. In + particular, the interface is modeled after std::map, and the various, + non-standard, std::hash_map. + + @library{wxbase} + @category{FIXME} +*/ +class wxHashMap +{ +public: + //@{ + /** + Copy constructor. + */ + wxHashMap(size_type size = 10); + wxHashMap(const wxHashMap& map); + //@} + + //@{ + /** + Returns an iterator pointing at the first element of the hash map. + Please remember that hash maps do not guarantee ordering. + */ + const_iterator begin(); + iterator begin(); + //@} + + /** + Removes all elements from the hash map. + */ + void clear(); + + /** + Counts the number of elements with the given key present in the map. + This function returns only 0 or 1. + */ + size_type count(const key_type& key); + + /** + Returns @true if the hash map does not contain any elements, @false otherwise. + */ + bool empty(); + + //@{ + /** + Returns an iterator pointing at the one-after-the-last element of the hash map. + Please remember that hash maps do not guarantee ordering. + */ + const_iterator end(); + iterator end(); + //@} + + //@{ + /** + Erases the element pointed to by the iterator. After the deletion + the iterator is no longer valid and must not be used. + */ + size_type erase(const key_type& key); + void erase(iterator it); + void erase(const_iterator it); + //@} + + //@{ + /** + If an element with the given key is present, the functions returns + an iterator pointing at that element, otherwise an invalid iterator + is returned (i.e. hashmap.find( non_existent_key ) == hashmap.end()). + */ + iterator find(const key_type& key); + const_iterator find(const key_type& key); + //@} + + /** + Inserts the given value in the hash map. The return value is + equivalent to a @c std::pairiterator(), bool; + the iterator points to the inserted element, the boolean value + is @true if @c v was actually inserted. + */ + Insert_Result insert(const value_type& v); + + /** + Use the key as an array subscript. The only difference is that if the + given key is not present in the hash map, an element with the + default @c value_type() is inserted in the table. + */ + mapped_type operator[](const key_type& key); + + /** + Returns the number of elements in the map. + */ + size_type size(); +}; diff --git a/interface/hashset.h b/interface/hashset.h new file mode 100644 index 0000000000..144db17724 --- /dev/null +++ b/interface/hashset.h @@ -0,0 +1,98 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: hashset.h +// Purpose: documentation for wxHashSet class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHashSet + @wxheader{hashset.h} + + This is a simple, type-safe, and reasonably efficient hash set class, + whose interface is a subset of the interface of STL containers. In + particular, the interface is modeled after std::set, and the various, + non-standard, std::hash_map. + + @library{wxbase} + @category{FIXME} +*/ +class wxHashSet +{ +public: + //@{ + /** + Copy constructor. + */ + wxHashSet(size_type size = 10); + wxHashSet(const wxHashSet& set); + //@} + + //@{ + /** + Returns an iterator pointing at the first element of the hash set. + Please remember that hash sets do not guarantee ordering. + */ + const_iterator begin(); + iterator begin(); + //@} + + /** + Removes all elements from the hash set. + */ + void clear(); + + /** + Counts the number of elements with the given key present in the set. + This function returns only 0 or 1. + */ + size_type count(const key_type& key); + + /** + Returns @true if the hash set does not contain any elements, @false otherwise. + */ + bool empty(); + + //@{ + /** + Returns an iterator pointing at the one-after-the-last element of the hash set. + Please remember that hash sets do not guarantee ordering. + */ + const_iterator end(); + iterator end(); + //@} + + //@{ + /** + Erases the element pointed to by the iterator. After the deletion + the iterator is no longer valid and must not be used. + */ + size_type erase(const key_type& key); + void erase(iterator it); + void erase(const_iterator it); + //@} + + //@{ + /** + If an element with the given key is present, the functions returns + an iterator pointing at that element, otherwise an invalid iterator + is returned (i.e. hashset.find( non_existent_key ) == hashset.end()). + */ + iterator find(const key_type& key); + const_iterator find(const key_type& key); + //@} + + /** + Inserts the given value in the hash set. The return value is + equivalent to a @c std::pairwxHashMap::iterator, bool; + the iterator points to the inserted element, the boolean value + is @true if @c v was actually inserted. + */ + Insert_Result insert(const value_type& v); + + /** + Returns the number of elements in the set. + */ + size_type size(); +}; diff --git a/interface/help.h b/interface/help.h new file mode 100644 index 0000000000..23b83bf7bc --- /dev/null +++ b/interface/help.h @@ -0,0 +1,267 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: help.h +// Purpose: documentation for wxHelpController class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHelpController + @wxheader{help.h} + + This is a family of classes by which + applications may invoke a help viewer to provide on-line help. + + A help controller allows an application to display help, at the contents + or at a particular topic, and shut the help program down on termination. + This avoids proliferation of many instances of the help viewer whenever the + user requests a different topic via the application's menus or buttons. + + Typically, an application will create a help controller instance + when it starts, and immediately call @b Initialize + to associate a filename with it. The help viewer will only get run, however, + just before the first call to display something. + + Most help controller classes actually derive from wxHelpControllerBase and have + names of the form wxXXXHelpController or wxHelpControllerXXX. An + appropriate class is aliased to the name wxHelpController for each platform, as + follows: + + On desktop Windows, wxCHMHelpController is used (MS HTML Help). + On Windows CE, wxWinceHelpController is used. + On all other platforms, wxHtmlHelpController is used if wxHTML is + compiled into wxWidgets; otherwise wxExtHelpController is used (for invoking an + external + browser). + + The remaining help controller classes need to be named + explicitly by an application that wishes to make use of them. + + There are currently the following help controller classes defined: + + wxWinHelpController, for controlling Windows Help. + wxCHMHelpController, for controlling MS HTML Help. To use this, you need to + set wxUSE_MS_HTML_HELP + to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you + don't need + VC++ specific htmlhelp.lib because wxWidgets loads necessary DLL at runtime and + so it + works with all compilers). + wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime + is + not available, wxHtmlHelpController. You need to provide + @b both CHM and HTB versions of the help file. For 32bit Windows only. + wxExtHelpController, for controlling external browsers under Unix. + The default browser is Netscape Navigator. The 'help' sample shows its use. + wxWinceHelpController, for controlling a simple @c .htm help controller for + Windows CE applications. + wxHtmlHelpController, a sophisticated help controller using wxHTML, in + a similar style to the Microsoft HTML Help viewer and using some of the same + files. + Although it has an API compatible with other help controllers, it has more + advanced features, so it is + recommended that you use the specific API for this class instead. Note that if + you + use .zip or .htb formats for your books, you + must add this line to your application initialization: @c + wxFileSystem::AddHandler(new wxArchiveFSHandler); + or nothing will be shown in your help window. + + + @library{wxbase} + @category{help} + + @seealso + wxHtmlHelpController, wxHTML +*/ +class wxHelpController : public wxObject +{ +public: + /** + Constructs a help instance object, but does not invoke the help viewer. + + If you provide a window, it will be used by some help controller classes, such + as + wxCHMHelpController, wxWinHelpController and wxHtmlHelpController, as the + parent for the help window instead of the value of wxApp::GetTopWindow. You can + also change the parent window later with + SetParentWindow(). + */ + wxHelpController(wxWindow* parentWindow = @NULL); + + /** + Destroys the help instance, closing down the viewer if it is running. + */ + ~wxHelpController(); + + /** + If the help viewer is not running, runs it and displays the file at the given + block number. + + @e WinHelp: Refers to the context number. + + @e MS HTML Help: Refers to the context number. + + @e External HTML help: the same as for DisplaySection(). + + @e wxHtmlHelpController: @e sectionNo is an identifier as specified in the @c + .hhc file. See @ref overview_helpformat "Help files format". + + This function is for backward compatibility only, and applications should use + @ref displaysection() wxHelpController instead. + */ + virtual bool DisplayBlock(long blockNo); + + /** + If the help viewer is not running, runs it and displays the + contents. + */ + virtual bool DisplayContents(); + + /** + Displays the section as a popup window using a context id. + + Returns @false if unsuccessful or not implemented. + */ + virtual bool DisplayContextPopup(int contextId); + + //@{ + /** + If the help viewer is not running, runs it and displays the given section. + + @e WinHelp, MS HTML Help @e sectionNo is a context id. + + @e External HTML help: wxExtHelpController implements @e sectionNo as an id in + a map file, which is of the form: + @e wxHtmlHelpController: @e sectionNo is an identifier as specified in the @c + .hhc file. See @ref overview_helpformat "Help files format". + + See also the help sample for notes on how to specify section numbers for + various help file formats. + */ + virtual bool DisplaySection(const wxString& section); + virtual bool DisplaySection(int sectionNo); + //@} + + /** + Displays the text in a popup window, if possible. + + Returns @false if unsuccessful or not implemented. + */ + virtual bool DisplayTextPopup(const wxString& text, + const wxPoint& pos); + + /** + wxHtmlHelpController returns the frame, size and position. + + For all other help controllers, this function does nothing + and just returns @NULL. + + @param viewer + This defaults to "netscape" for wxExtHelpController. + + @param flags + This defaults to wxHELP_NETSCAPE for wxExtHelpController, indicating + that the viewer is a variant of Netscape Navigator. + */ + virtual wxFrame * GetFrameParameters(const wxSize * size = @NULL, + const wxPoint * pos = @NULL, + bool * newFrameEachTime = @NULL); + + /** + Returns the window to be used as the parent for the help window. This window is + used + by wxCHMHelpController, wxWinHelpController and wxHtmlHelpController. + */ + virtual wxWindow* GetParentWindow(); + + //@{ + /** + Initializes the help instance with a help filename, and optionally a server + socket + number if using wxHelp (now obsolete). Does not invoke the help viewer. + This must be called directly after the help instance object is created and + before + any attempts to communicate with the viewer. + + You may omit the file extension and a suitable one will be chosen. For + wxHtmlHelpController, the extensions zip, htb and hhp will be appended while + searching for + a suitable file. For WinHelp, the hlp extension is appended. + */ + virtual bool Initialize(const wxString& file); + virtual bool Initialize(const wxString& file, int server); + //@} + + /** + If the help viewer is not running, runs it, and searches for sections matching + the given keyword. If one match is found, the file is displayed at this + section. The optional parameter allows the search the index + (wxHELP_SEARCH_INDEX) but this currently only supported by the + wxHtmlHelpController. + + @e WinHelp, MS HTML Help: If more than one match is found, + the first topic is displayed. + + @e External HTML help, simple wxHTML help: If more than one match is found, + a choice of topics is displayed. + + @e wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch. + */ + virtual bool KeywordSearch(const wxString& keyWord, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + + /** + If the help viewer is not running, runs it and loads the given file. + If the filename is not supplied or is + empty, the file specified in @b Initialize is used. If the viewer is + already displaying the specified file, it will not be reloaded. This + member function may be used before each display call in case the user + has opened another file. + + wxHtmlHelpController ignores this call. + */ + virtual bool LoadFile(const wxString& file = ""); + + /** + Overridable member called when this application's viewer is quit by the user. + + This does not work for all help controllers. + */ + virtual bool OnQuit(); + + /** + If the viewer is running, quits it by disconnecting. + + For Windows Help, the viewer will only close if no other application is using + it. + */ + virtual bool Quit(); + + /** + For wxHtmlHelpController, the title is set (again with %s indicating the + page title) and also the size and position of the frame if the frame is already + open. @e newFrameEachTime is ignored. + + For all other help controllers this function has no effect. + */ + virtual void SetFrameParameters(const wxString & title, + const wxSize & size, + const wxPoint & pos = wxDefaultPosition, + bool newFrameEachTime = @false); + + /** + Sets the window to be used as the parent for the help window. This is used + by wxCHMHelpController, wxWinHelpController and wxHtmlHelpController. + */ + virtual void SetParentWindow(wxWindow* parentWindow); + + /** + Sets detailed viewer information. So far this is only relevant to + wxExtHelpController. + + Some examples of usage: + */ + virtual void SetViewer(const wxString& viewer, long flags); +}; diff --git a/interface/html/helpctrl.h b/interface/html/helpctrl.h new file mode 100644 index 0000000000..ea193f3b91 --- /dev/null +++ b/interface/html/helpctrl.h @@ -0,0 +1,212 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpctrl.h +// Purpose: documentation for wxHtmlHelpController class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpController + @headerfile helpctrl.h wx/html/helpctrl.h + + This help controller provides an easy way of displaying HTML help in your + application (see @e test sample). The help system is based on @b books + (see wxHtmlHelpController::AddBook). A book is a logical + section of documentation (for example "User's Guide" or "Programmer's Guide" or + "C++ Reference" or "wxWidgets Reference"). The help controller can handle as + many books as you want. + + Although this class has an API compatible with other wxWidgets + help controllers as documented by wxHelpController, it + is recommended that you use the enhanced capabilities of wxHtmlHelpController's + API. + + wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as + its + native format. The file format is described here. + Have a look at docs/html/ directory where sample project files are stored. + + You can use Tex2RTF to produce these files when generating HTML, if you set @b + htmlWorkshopFiles to @b @true in + your tex2rtf.ini file. The commercial tool HelpBlocks (www.helpblocks.com) can + also create these files. + + @library{wxhtml} + @category{help} + + @seealso + @ref overview_wxhelpcontroller "Information about wxBestHelpController", + wxHtmlHelpFrame, wxHtmlHelpDialog, wxHtmlHelpWindow, wxHtmlModalHelp +*/ +class wxHtmlHelpController +{ +public: + /** + Constructor. + */ + wxHtmlHelpController(int style = wxHF_DEFAULT_STYLE, + wxWindow* parentWindow = @NULL); + + //@{ + /** + Adds book (@ref overview_helpformat ".hhp file" - HTML Help Workshop project + file) into the list of loaded books. + This must be called at least once before displaying any help. + + @e bookFile or @e bookUrl may be either .hhp file or ZIP archive + that contains arbitrary number of .hhp files in + top-level directory. This ZIP archive must have .zip or .htb extension + (the latter stands for "HTML book"). In other words, @c + AddBook(wxFileName("help.zip")) + is possible and is the recommended way. + + @param showWaitMsg + If @true then a decoration-less window with progress message is displayed. + + @param bookFile + Help book filename. It is recommended to use this prototype + instead of the one taking URL, because it is less error-prone. + + @param bookUrl + Help book URL (note that syntax of filename and URL is + different on most platforms) + */ + bool AddBook(const wxFileName& bookFile, bool showWaitMsg); + bool AddBook(const wxString& bookUrl, bool showWaitMsg); + //@} + + /** + This protected virtual method may be overridden so that when specifying the + wxHF_DIALOG style, the controller + uses a different dialog. + */ + virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData * data); + + /** + This protected virtual method may be overridden so that the controller + uses a different frame. + */ + virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData * data); + + //@{ + /** + This alternative form is used to search help contents by numeric IDs. + */ + void Display(const wxString& x); + void Display(const int id); + //@} + + /** + Displays help window and focuses contents panel. + */ + void DisplayContents(); + + /** + Displays help window and focuses index panel. + */ + void DisplayIndex(); + + /** + Displays help window, focuses search panel and starts searching. Returns @true + if the keyword was found. Optionally it searches through the index (mode = + wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL). + + @b Important: KeywordSearch searches only pages listed in .hhc file(s). + You should list all pages in the contents file. + */ + bool KeywordSearch(const wxString& keyword, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + + /** + Reads the controller's setting (position of window, etc.) + */ + void ReadCustomization(wxConfigBase* cfg, + wxString path = wxEmptyString); + + /** + Sets the path for storing temporary files - cached binary versions of index and + contents files. These binary + forms are much faster to read. Default value is empty string (empty string means + that no cached data are stored). Note that these files are @e not + deleted when program exits. + + Once created these cached files will be used in all subsequent executions + of your application. If cached files become older than corresponding .hhp + file (e.g. if you regenerate documentation) it will be refreshed. + */ + void SetTempDir(const wxString& path); + + /** + Sets format of title of the frame. Must contain exactly one "%s" + (for title of displayed HTML page). + */ + void SetTitleFormat(const wxString& format); + + /** + Associates @e config object with the controller. + + If there is associated config object, wxHtmlHelpController automatically + reads and writes settings (including wxHtmlWindow's settings) when needed. + + The only thing you must do is create wxConfig object and call UseConfig. + + If you do not use @e UseConfig, wxHtmlHelpController will use + default wxConfig object if available (for details see + wxConfigBase::Get and + wxConfigBase::Set). + */ + void UseConfig(wxConfigBase* config, + const wxString& rootpath = wxEmptyString); + + /** + Stores controllers setting (position of window etc.) + */ + void WriteCustomization(wxConfigBase* cfg, + wxString path = wxEmptyString); +}; + + +/** + @class wxHtmlModalHelp + @headerfile helpctrl.h wx/html/helpctrl.h + + This class uses wxHtmlHelpController + to display help in a modal dialog. This is useful on platforms such as wxMac + where if you display help from a modal dialog, the help window must itself be a + modal + dialog. + + Create objects of this class on the stack, for example: + + @code + // The help can be browsed during the lifetime of this object; when the user + quits + // the help, program execution will continue. + wxHtmlModalHelp help(parent, wxT("help"), wxT("My topic")); + @endcode + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlModalHelp +{ +public: + /** + @param parent + is the parent of the dialog. + + @param helpFile + is the HTML help file to show. + + @param topic + is an optional topic. If this is empty, the help contents will be shown. + + @param style + is a combination of the flags described in the wxHtmlHelpController + documentation. + */ + wxHtmlModalHelp(wxWindow* parent, const wxString& helpFile, + const wxString& topic = wxEmptyString, + int style = wxHF_DEFAULT_STYLE | wxHF_DIALOG | wxHF_MODAL); +}; diff --git a/interface/html/helpdata.h b/interface/html/helpdata.h new file mode 100644 index 0000000000..ea62c1763f --- /dev/null +++ b/interface/html/helpdata.h @@ -0,0 +1,68 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpdata.h +// Purpose: documentation for wxHtmlHelpData class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpData + @headerfile helpdata.h wx/html/helpdata.h + + This class is used by wxHtmlHelpController + and wxHtmlHelpFrame to access HTML help items. + It is internal class and should not be used directly - except for the case + you're writing your own HTML help controller. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlHelpData : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlHelpData(); + + /** + Adds new book. @e book is URL (not filename!) of HTML help project (hhp) + or ZIP file that contains arbitrary number of .hhp projects (this zip + file can have either .zip or .htb extension, htb stands for "html book"). + Returns success. + */ + bool AddBook(const wxString& book_url); + + /** + Returns page's URL based on integer ID stored in project. + */ + wxString FindPageById(int id); + + /** + Returns page's URL based on its (file)name. + */ + wxString FindPageByName(const wxString& page); + + /** + Returns array with help books info. + */ + const wxHtmlBookRecArray GetBookRecArray(); + + /** + Returns reference to array with contents entries. + */ + const wxHtmlHelpDataItems GetContentsArray(); + + /** + Returns reference to array with index entries. + */ + const wxHtmlHelpDataItems GetIndexArray(); + + /** + Sets temporary directory where binary cached versions of MS HTML Workshop + files will be stored. (This is turned off by default and you can enable + this feature by setting non-empty temp dir.) + */ + void SetTempDir(const wxString& path); +}; diff --git a/interface/html/helpdlg.h b/interface/html/helpdlg.h new file mode 100644 index 0000000000..43768d9694 --- /dev/null +++ b/interface/html/helpdlg.h @@ -0,0 +1,82 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpdlg.h +// Purpose: documentation for wxHtmlHelpDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpDialog + @headerfile helpdlg.h wx/html/helpdlg.h + + This class is used by wxHtmlHelpController + to display help. + It is an internal class and should not be used directly - except for the case + when you're writing your own HTML help controller. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlHelpDialog : public wxFrame +{ +public: + //@{ + /** + Constructor. For the values of @e style, please see the documentation for + wxHtmlHelpController. + */ + wxHtmlHelpDialog(wxHtmlHelpData* data = @NULL); + wxHtmlHelpDialog(wxWindow* parent, int wxWindowID, + const wxString& title = wxEmptyString, + int style = wxHF_DEFAULT_STYLE, + wxHtmlHelpData* data = @NULL); + //@} + + /** + You may override this virtual method to add more buttons to the help window's + toolbar. @e toolBar is a pointer to the toolbar and @e style is the style + flag as passed to the Create method. + + wxToolBar::Realize is called immediately after returning from this function. + */ + virtual void AddToolbarButtons(wxToolBar * toolBar, int style); + + /** + Creates the dialog. See @ref wxhtmlhelpdialog() "the constructor" + for a description of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title = wxEmptyString, + int style = wxHF_DEFAULT_STYLE); + + /** + Returns the help controller associated with the dialog. + */ + wxHtmlHelpController* GetController(); + + /** + Reads the user's settings for this dialog see + wxHtmlHelpController::ReadCustomization) + */ + void ReadCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); + + /** + Sets the help controller associated with the dialog. + */ + void SetController(wxHtmlHelpController* contoller); + + /** + Sets the dialog's title format. @e format must contain exactly one "%s" + (it will be replaced by the page title). + */ + void SetTitleFormat(const wxString& format); + + /** + Saves the user's settings for this dialog (see + wxHtmlHelpController::WriteCustomization). + */ + void WriteCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); +}; diff --git a/interface/html/helpfrm.h b/interface/html/helpfrm.h new file mode 100644 index 0000000000..d9a0f7ce49 --- /dev/null +++ b/interface/html/helpfrm.h @@ -0,0 +1,82 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpfrm.h +// Purpose: documentation for wxHtmlHelpFrame class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpFrame + @headerfile helpfrm.h wx/html/helpfrm.h + + This class is used by wxHtmlHelpController + to display help. + It is an internal class and should not be used directly - except for the case + when you're writing your own HTML help controller. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlHelpFrame : public wxFrame +{ +public: + //@{ + /** + Constructor. For the values of @e style, please see the documentation for + wxHtmlHelpController. + */ + wxHtmlHelpFrame(wxHtmlHelpData* data = @NULL); + wxHtmlHelpFrame(wxWindow* parent, int wxWindowID, + const wxString& title = wxEmptyString, + int style = wxHF_DEFAULT_STYLE, + wxHtmlHelpData* data = @NULL); + //@} + + /** + You may override this virtual method to add more buttons to the help window's + toolbar. @e toolBar is a pointer to the toolbar and @e style is the style + flag as passed to the Create method. + + wxToolBar::Realize is called immediately after returning from this function. + */ + virtual void AddToolbarButtons(wxToolBar * toolBar, int style); + + /** + Creates the frame. See @ref wxhtmlhelpframe() "the constructor" + for a description of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title = wxEmptyString, + int style = wxHF_DEFAULT_STYLE); + + /** + Returns the help controller associated with the frame. + */ + wxHtmlHelpController* GetController(); + + /** + Reads the user's settings for this frame see + wxHtmlHelpController::ReadCustomization) + */ + void ReadCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); + + /** + Sets the help controller associated with the frame. + */ + void SetController(wxHtmlHelpController* contoller); + + /** + Sets the frame's title format. @e format must contain exactly one "%s" + (it will be replaced by the page title). + */ + void SetTitleFormat(const wxString& format); + + /** + Saves the user's settings for this frame (see + wxHtmlHelpController::WriteCustomization). + */ + void WriteCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); +}; diff --git a/interface/html/helpwnd.h b/interface/html/helpwnd.h new file mode 100644 index 0000000000..d4b9855f9a --- /dev/null +++ b/interface/html/helpwnd.h @@ -0,0 +1,175 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpwnd.h +// Purpose: documentation for wxHtmlHelpWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpWindow + @headerfile helpwnd.h wx/html/helpwnd.h + + This class is used by wxHtmlHelpController + to display help within a frame or dialog, but you can use it yourself to create + an embedded HTML help window. + + For example: + + @code + // m_embeddedHelpWindow is a wxHtmlHelpWindow + // m_embeddedHtmlHelp is a wxHtmlHelpController + + // Create embedded HTML Help window + m_embeddedHelpWindow = new wxHtmlHelpWindow; + m_embeddedHtmlHelp.UseConfig(config, rootPath); // Set your own config + object here + m_embeddedHtmlHelp.SetHelpWindow(m_embeddedHelpWindow); + m_embeddedHelpWindow-Create(this, + wxID_ANY, wxDefaultPosition, GetClientSize(), + wxTAB_TRAVERSAL|wxBORDER_NONE, wxHF_DEFAULT_STYLE); + m_embeddedHtmlHelp.AddBook(wxFileName(_T("doc.zip"))); + @endcode + + You should pass the style wxHF_EMBEDDED to the style parameter of + wxHtmlHelpController to allow + the embedded window to be destroyed independently of the help controller. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlHelpWindow : public wxWindow +{ +public: + //@{ + /** + Constructor. + + Constructor. For the values of @e helpStyle, please see the documentation for + wxHtmlHelpController. + */ + wxHtmlHelpWindow(wxHtmlHelpData* data = @NULL); + wxHtmlHelpWindow(wxWindow* parent, int wxWindowID, + const wxPoint& pos = wxDefaultPosition, + const wxSize& pos = wxDefaultSize, + int style = wxTAB_TRAVERSAL|wxBORDER_NONE, + int helpStyle = wxHF_DEFAULT_STYLE, + wxHtmlHelpData* data = @NULL); + //@} + + /** + You may override this virtual method to add more buttons to the help window's + toolbar. @e toolBar is a pointer to the toolbar and @e style is the style + flag as passed to the Create method. + + wxToolBar::Realize is called immediately after returning from this function. + + See @e samples/html/helpview for an example. + */ + virtual void AddToolbarButtons(wxToolBar * toolBar, int style); + + /** + Creates the help window. See @ref wxhtmlhelpwindow() "the constructor" + for a description of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& pos = wxDefaultSize, + int style = wxTAB_TRAVERSAL|wxBORDER_NONE, + int helpStyle = wxHF_DEFAULT_STYLE, + wxHtmlHelpData* data = @NULL); + + /** + Creates contents panel. (May take some time.) + + Protected. + */ + void CreateContents(); + + /** + Creates index panel. (May take some time.) + + Protected. + */ + void CreateIndex(); + + /** + Creates search panel. + */ + void CreateSearch(); + + //@{ + /** + Displays page x. If not found it will give the user the choice of + searching books. + Looking for the page runs in these steps: + + try to locate file named x (if x is for example "doc/howto.htm") + try to open starting page of book x + try to find x in contents (if x is for example "How To ...") + try to find x in index (if x is for example "How To ...") + + The second form takes numeric ID as the parameter. + (uses extension to MS format, param name="ID" value=id) + */ + bool Display(const wxString& x); + bool Display(const int id); + //@} + + /** + Displays contents panel. + */ + bool DisplayContents(); + + /** + Displays index panel. + */ + bool DisplayIndex(); + + /** + Returns the wxHtmlHelpData object, which is usually a pointer to the + controller's data. + */ + wxHtmlHelpData* GetData(); + + /** + Search for given keyword. Optionally it searches through the index (mode = + wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL). + */ + bool KeywordSearch(const wxString& keyword, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + + /** + Reads the user's settings for this window (see + wxHtmlHelpController::ReadCustomization) + */ + void ReadCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); + + /** + Refresh all panels. This is necessary if a new book was added. + + Protected. + */ + void RefreshLists(); + + /** + Sets the frame's title format. @e format must contain exactly one "%s" + (it will be replaced by the page title). + */ + void SetTitleFormat(const wxString& format); + + /** + Associates a wxConfig object with the help window. It is recommended that you + use wxHtmlHelpController::UseConfig instead. + */ + void UseConfig(wxConfigBase* config, + const wxString& rootpath = wxEmptyString); + + /** + Saves the user's settings for this window(see + wxHtmlHelpController::WriteCustomization). + */ + void WriteCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); +}; diff --git a/interface/html/htmlcell.h b/interface/html/htmlcell.h new file mode 100644 index 0000000000..9fed378057 --- /dev/null +++ b/interface/html/htmlcell.h @@ -0,0 +1,628 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmlcell.h +// Purpose: documentation for wxHtmlColourCell class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlColourCell + @headerfile htmlcell.h wx/html/htmlcell.h + + This cell changes the colour of either the background or the foreground. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlColourCell : public wxHtmlCell +{ +public: + /** + Constructor. + + @param clr + The color + + @param flags + Can be one of following: + + wxHTML_CLR_FOREGROUND + + + change color of text + + wxHTML_CLR_BACKGROUND + + + change background color + */ + wxHtmlColourCell(wxColour clr, int flags = wxHTML_CLR_FOREGROUND); +}; + + +/** + @class wxHtmlWidgetCell + @headerfile htmlcell.h wx/html/htmlcell.h + + wxHtmlWidgetCell is a class that provides a connection between HTML cells and + widgets (an object derived + from wxWindow). You can use it to display things like forms, input boxes etc. + in an HTML window. + + wxHtmlWidgetCell takes care of resizing and moving window. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlWidgetCell : public wxHtmlCell +{ +public: + /** + Constructor. + + @param wnd + Connected window. It is parent window must be the wxHtmlWindow object within + which it is displayed! + + @param w + Floating width. If non-zero width of wnd window is adjusted so that it is + always w percents of parent container's width. (For example w = 100 means that + the window + will always have same width as parent container) + */ + wxHtmlWidgetCell(wxWindow* wnd, int w = 0); +}; + + +/** + @class wxHtmlCell + @headerfile htmlcell.h wx/html/htmlcell.h + + Internal data structure. It represents fragments of parsed HTML + page, the so-called @b cell - a word, picture, table, horizontal line and so on. + It is used by wxHtmlWindow and + wxHtmlWinParser to represent HTML page in memory. + + You can divide cells into two groups : @e visible cells with non-zero width and + height and @e helper cells (usually with zero width and height) that + perform special actions such as color or font change. + + @library{wxhtml} + @category{FIXME} + + @seealso + @ref overview_cells "Cells Overview", wxHtmlContainerCell +*/ +class wxHtmlCell : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlCell(); + + /** + This method is used to adjust pagebreak position. The parameter is + variable that contains y-coordinate of page break (= horizontal line that + should not be crossed by words, images etc.). If this cell cannot be divided + into two pieces (each one on another page) then it moves the pagebreak + few pixels up. + + Returns @true if pagebreak was modified, @false otherwise + + Usage: + */ + virtual bool AdjustPagebreak(int * pagebreak); + + /** + Renders the cell. + + @param dc + Device context to which the cell is to be drawn + + @param x,y + Coordinates of parent's upper left corner (origin). You must + add this to m_PosX,m_PosY when passing coordinates to dc's methods + Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + + @param view_y1 + y-coord of the first line visible in window. This is + used to optimize rendering speed + + @param view_y2 + y-coord of the last line visible in window. This is + used to optimize rendering speed + */ + virtual void Draw(wxDC& dc, int x, int y, int view_y1, + int view_y2); + + /** + This method is called instead of Draw() when the + cell is certainly out of the screen (and thus invisible). This is not + nonsense - some tags (like wxHtmlColourCell + or font setter) must be drawn even if they are invisible! + + @param dc + Device context to which the cell is to be drawn + + @param x,y + Coordinates of parent's upper left corner. You must + add this to m_PosX,m_PosY when passing coordinates to dc's methods + Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + */ + virtual void DrawInvisible(wxDC& dc, int x, int y); + + /** + Returns pointer to itself if this cell matches condition (or if any of the cells + following in the list matches), @NULL otherwise. + (In other words if you call top-level container's Find it will + return pointer to the first cell that matches the condition) + + It is recommended way how to obtain pointer to particular cell or + to cell of some type (e.g. wxHtmlAnchorCell reacts on + wxHTML_COND_ISANCHOR condition) + + @param condition + Unique integer identifier of condition + + @param param + Optional parameters + */ + virtual const wxHtmlCell* Find(int condition, const void* param); + + /** + Returns descent value of the cell (m_Descent member). + See explanation: + */ + int GetDescent(); + + /** + 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. + + @b Note: This shouldn't be used by the end user. If you need some way of + finding particular cell in the list, try Find() method + instead. + */ + wxHtmlCell* GetFirstChild(); + + /** + Returns height of the cell (m_Height member). + */ + int GetHeight(); + + /** + Returns unique cell identifier if there is any, empty string otherwise. + */ + virtual wxString GetId(); + + /** + Returns hypertext link if associated with this cell or @NULL otherwise. + See wxHtmlLinkInfo. + (Note: this makes sense only for visible tags). + + @param x,y + Coordinates of position where the user pressed mouse button. + These coordinates are used e.g. by COLORMAP. Values are relative to the + upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height) + */ + virtual wxHtmlLinkInfo* GetLink(int x = 0, int y = 0); + + /** + Returns cursor to show when mouse pointer is over the cell. + + @param window + interface to the parent HTML window + */ + virtual wxCursor GetMouseCursor(wxHtmlWindowInterface* window); + + /** + Returns pointer to the next cell in list (see htmlcell.h if you're + interested in details). + */ + wxHtmlCell* GetNext(); + + /** + Returns pointer to parent container. + */ + wxHtmlContainerCell* GetParent(); + + /** + Returns X position within parent (the value is relative to parent's + upper left corner). The returned value is meaningful only if + parent's Layout() was called before! + */ + int GetPosX(); + + /** + Returns Y position within parent (the value is relative to parent's + upper left corner). The returned value is meaningful only if + parent's Layout() was called before! + */ + int GetPosY(); + + /** + Returns width of the cell (m_Width member). + */ + int GetWidth(); + + /** + This method performs two actions: + + adjusts the cell's width according to the fact that maximal possible width is + @e w. + (this has sense when working with horizontal lines, tables etc.) + prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members) + based on actual width @e w + + It must be called before displaying cells structure because + m_PosX and m_PosY are undefined (or invalid) + before calling Layout. + */ + virtual void Layout(int w); + + /** + This function is simple event handler. Each time the user clicks mouse button + over a cell within wxHtmlWindow this method of that + cell is called. Default behavior is to call + wxHtmlWindow::LoadPage. + + @param window + interface to the parent HTML window + + @param pos + coordinates of mouse click (this is relative to cell's origin + + @param event + mouse event that triggered the call + + @returns @true if a link was clicked, @false otherwise. + */ + virtual bool ProcessMouseClick(wxHtmlWindowInterface* window, + const wxPoint& pos, + const wxMouseEvent& event); + + /** + Sets unique cell identifier. Default value is no identifier, i.e. empty string. + */ + void SetId(const wxString& id); + + /** + Sets the hypertext link associated with this cell. (Default value + is wxHtmlLinkInfo("", "") (no link)) + */ + void SetLink(const wxHtmlLinkInfo& link); + + /** + Sets the next cell in the list. This shouldn't be called by user - it is + to be used only by wxHtmlContainerCell::InsertCell. + */ + void SetNext(wxHtmlCell cell); + + /** + Sets parent container of this cell. This is called from + wxHtmlContainerCell::InsertCell. + */ + void SetParent(wxHtmlContainerCell p); + + /** + Sets the cell's position within parent container. + */ + void SetPos(int x, int y); +}; + + +/** + @class wxHtmlContainerCell + @headerfile htmlcell.h wx/html/htmlcell.h + + The wxHtmlContainerCell class is an implementation of a cell that may + contain more cells in it. It is heavily used in the wxHTML layout algorithm. + + @library{wxhtml} + @category{FIXME} + + @seealso + @ref overview_cells "Cells Overview" +*/ +class wxHtmlContainerCell : public wxHtmlCell +{ +public: + /** + Constructor. @e parent is pointer to parent container or @NULL. + */ + wxHtmlContainerCell(wxHtmlContainerCell parent); + + /** + Returns container's horizontal alignment. + */ + int GetAlignHor(); + + /** + Returns container's vertical alignment. + */ + int GetAlignVer(); + + /** + Returns the background colour of the container or @c wxNullColour if no + background + colour is set. + */ + wxColour GetBackgroundColour(); + + /** + Returns the indentation. @e ind is one of the @b wxHTML_INDENT_* constants. + + @b Note: You must call GetIndentUnits() + with same @e ind parameter in order to correctly interpret the returned integer + value. + It is NOT always in pixels! + */ + int GetIndent(int ind); + + /** + Returns the units of indentation for @e ind where @e ind is one + of the @b wxHTML_INDENT_* constants. + */ + int GetIndentUnits(int ind); + + /** + Inserts new cell into the container. + */ + void InsertCell(wxHtmlCell cell); + + /** + Sets the container's alignment (both horizontal and vertical) according to + the values stored in @e tag. (Tags @c ALIGN parameter is extracted.) In fact + it is only a front-end to SetAlignHor() + and SetAlignVer(). + */ + void SetAlign(const wxHtmlTag& tag); + + /** + Sets the container's @e horizontal alignment. During wxHtmlCell::Layout + each line is aligned according to @e al value. + + @param al + new horizontal alignment. May be one of these values: + + wxHTML_ALIGN_LEFT + + + lines are left-aligned (default) + + wxHTML_ALIGN_JUSTIFY + + + lines are justified + + wxHTML_ALIGN_CENTER + + + lines are centered + + wxHTML_ALIGN_RIGHT + + + lines are right-aligned + */ + void SetAlignHor(int al); + + /** + Sets the container's @e vertical alignment. This is per-line alignment! + + @param al + new vertical alignment. May be one of these values: + + wxHTML_ALIGN_BOTTOM + + + cells are over the line (default) + + wxHTML_ALIGN_CENTER + + + cells are centered on line + + wxHTML_ALIGN_TOP + + + cells are under the line + */ + void SetAlignVer(int al); + + /** + Sets the background colour for this container. + */ + void SetBackgroundColour(const wxColour& clr); + + /** + Sets the border (frame) colours. A border is a rectangle around the container. + + @param clr1 + Colour of top and left lines + + @param clr2 + Colour of bottom and right lines + */ + void SetBorder(const wxColour& clr1, const wxColour& clr2); + + /** + Sets the indentation (free space between borders of container and subcells). + + @param i + Indentation value. + + @param what + Determines which of the four borders we're setting. It is OR + combination of following constants: + + wxHTML_INDENT_TOP + + + top border + + wxHTML_INDENT_BOTTOM + + + bottom + + wxHTML_INDENT_LEFT + + + left + + wxHTML_INDENT_RIGHT + + + right + + wxHTML_INDENT_HORIZONTAL + + + left and right + + wxHTML_INDENT_VERTICAL + + + top and bottom + + wxHTML_INDENT_ALL + + + all 4 borders + + + @param units + Units of i. This parameter affects interpretation of value. + + wxHTML_UNITS_PIXELS + + + i is number of pixels + + wxHTML_UNITS_PERCENT + + + i is interpreted as percents of width + of parent container + */ + void SetIndent(int i, int what, int units = wxHTML_UNITS_PIXELS); + + /** + Sets minimal height of the container. + + When container's wxHtmlCell::Layout is called, m_Height + is set depending on layout of subcells to the height of area covered + by layed-out subcells. Calling this method guarantees you that the height + of container is never smaller than @e h - even if the subcells cover + much smaller area. + + @param h + The minimal height. + + @param align + If height of the container is lower than the minimum height, empty space must + be inserted + somewhere in order to ensure minimal height. This parameter is one of + wxHTML_ALIGN_TOP, + wxHTML_ALIGN_BOTTOM, wxHTML_ALIGN_CENTER. It refers to the contents, not to the + empty place. + */ + void SetMinHeight(int h, int align = wxHTML_ALIGN_TOP); + + //@{ + /** + Sets floating width adjustment. + + The normal behaviour of container is that its width is the same as the width of + parent container (and thus you can have only one sub-container per line). + You can change this by setting FWA. + + @e pixel_scale is number of real pixels that equals to 1 HTML pixel. + + @param w + Width of the container. If the value is negative it means + complement to full width of parent container (e.g. + SetWidthFloat(-50, wxHTML_UNITS_PIXELS) sets the width + of container to parent's width minus 50 pixels. This is useful when + creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50)) + + @param units + Units of w This parameter affects the interpretation of value. + + wxHTML_UNITS_PIXELS + + + w is number of pixels + + wxHTML_UNITS_PERCENT + + + w is interpreted as percents of width + of parent container + + @param tag + In the second version of method, w and units + info is extracted from tag's WIDTH parameter. + */ + void SetWidthFloat(int w, int units); + void SetWidthFloat(const wxHtmlTag& tag, + double pixel_scale = 1.0); + //@} +}; + + +/** + @class wxHtmlLinkInfo + @headerfile htmlcell.h wx/html/htmlcell.h + + This class stores all necessary information about hypertext + links (as represented by @c A tag in HTML documents). In + current implementation it stores URL and target frame name. + @e Note that frames are not currently supported by wxHTML! + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlLinkInfo : public wxObject +{ +public: + //@{ + /** + Construct hypertext link from HREF (aka URL) and TARGET (name of target + frame). + */ + wxHtmlLinkInfo(); + wxHtmlLinkInfo(const wxString& href, + const wxString& target = wxEmptyString); + //@} + + /** + Return pointer to event that generated OnLinkClicked event. Valid + only within wxHtmlWindow::OnLinkClicked, + @NULL otherwise. + */ + const wxMouseEvent * GetEvent(); + + /** + Return @e HREF value of the @c A tag. + */ + wxString GetHref(); + + /** + Return pointer to the cell that was clicked. Valid + only within wxHtmlWindow::OnLinkClicked, + @NULL otherwise. + */ + const wxHtmlCell * GetHtmlCell(); + + /** + Return @e TARGET value of the @c A tag (this value + is used to specify in which frame should be the page pointed + by @ref gethref() Href opened). + */ + wxString GetTarget(); +}; diff --git a/interface/html/htmlfilt.h b/interface/html/htmlfilt.h new file mode 100644 index 0000000000..238fb088a4 --- /dev/null +++ b/interface/html/htmlfilt.h @@ -0,0 +1,43 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmlfilt.h +// Purpose: documentation for wxHtmlFilter class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlFilter + @headerfile htmlfilt.h wx/html/htmlfilt.h + + This class is the parent class of input filters for wxHtmlWindow. + It allows you to read and display files of different file formats. + + @library{wxhtml} + @category{FIXME} + + @seealso + Overview +*/ +class wxHtmlFilter : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlFilter(); + + /** + Returns @true if this filter is capable of reading file @e file. + + Example: + */ + bool CanRead(const wxFSFile& file); + + /** + Reads the file and returns string with HTML document. + + Example: + */ + wxString ReadFile(const wxFSFile& file); +}; diff --git a/interface/html/htmlpars.h b/interface/html/htmlpars.h new file mode 100644 index 0000000000..8b074926c4 --- /dev/null +++ b/interface/html/htmlpars.h @@ -0,0 +1,262 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmlpars.h +// Purpose: documentation for wxHtmlTagHandler class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlTagHandler + @headerfile htmlpars.h wx/html/htmlpars.h + + + @library{wxhtml} + @category{html} + + @seealso + Overview, wxHtmlTag +*/ +class wxHtmlTagHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlTagHandler(); + + /** + Returns list of supported tags. The list is in uppercase and tags + are delimited by ','. Example : @c "I,B,FONT,P" + */ + virtual wxString GetSupportedTags(); + + /** + This is the core method of each handler. It is called each time + one of supported tags is detected. @e tag contains all necessary + info (see wxHtmlTag for details). + + @returns @true if ParseInner was called, @false otherwise. + */ + virtual bool HandleTag(const wxHtmlTag& tag); + + /** + This method calls parser's wxHtmlParser::DoParsing method + for the string between this tag and the paired ending tag: + In this example, a call to ParseInner (with @e tag pointing to A tag) + will parse 'Hello, world!'. + */ + void ParseInner(const wxHtmlTag& tag); + + /** + Assigns @e parser to this handler. Each @b instance of handler + is guaranteed to be called only from the parser. + */ + virtual void SetParser(wxHtmlParser parser); + + /** + @b wxHtmlParser* m_Parser + + This attribute is used to access parent parser. It is protected so that + it can't be accessed by user but can be accessed from derived classes. + */ +}; + + +/** + @class wxHtmlParser + @headerfile htmlpars.h wx/html/htmlpars.h + + Classes derived from this handle the @b generic parsing of HTML documents: it + scans + the document and divide it into blocks of tags (where one block + consists of beginning and ending tag and of text between these + two tags). + + It is independent from wxHtmlWindow and can be used as stand-alone parser + (Julian Smart's idea of speech-only HTML viewer or wget-like utility - + see InetGet sample for example). + + It uses system of tag handlers to parse the HTML document. Tag handlers + are not statically shared by all instances but are created for each + wxHtmlParser instance. The reason is that the handler may contain + document-specific temporary data used during parsing (e.g. complicated + structures like tables). + + Typically the user calls only the wxHtmlParser::Parse method. + + @library{wxhtml} + @category{html} + + @seealso + @ref overview_cells "Cells Overview", @ref overview_handlers "Tag Handlers + Overview", wxHtmlTag +*/ +class wxHtmlParser +{ +public: + /** + Constructor. + */ + wxHtmlParser(); + + /** + This may (and may not) be overwritten in derived class. + + This method is called each time new tag is about to be added. + @e tag contains information about the tag. (See wxHtmlTag + for details.) + + Default (wxHtmlParser) behaviour is this: + First it finds a handler capable of handling this tag and then it calls + handler's HandleTag method. + */ + void AddTag(const wxHtmlTag& tag); + + /** + Adds handler to the internal list ( hash table) of handlers. This + method should not be called directly by user but rather by derived class' + constructor. + + This adds the handler to this @b instance of wxHtmlParser, not to + all objects of this class! (Static front-end to AddTagHandler is provided + by wxHtmlWinParser). + + All handlers are deleted on object deletion. + */ + virtual void AddTagHandler(wxHtmlTagHandler handler); + + /** + Must be overwritten in derived class. + + This method is called by DoParsing() + each time a part of text is parsed. @e txt is NOT only one word, it is + substring of input. It is not formatted or preprocessed (so white spaces are + unmodified). + */ + virtual void AddWord(const wxString& txt); + + //@{ + /** + Parses the m_Source from begin_pos to end_pos-1. + (in noparams version it parses whole m_Source) + */ + void DoParsing(int begin_pos, int end_pos); + void DoParsing(); + //@} + + /** + This must be called after DoParsing(). + */ + virtual void DoneParser(); + + /** + Returns pointer to the file system. Because each tag handler has + reference to it is parent parser it can easily request the file by + calling + */ +#define wxFileSystem* GetFS() /* implementation is private */ + + /** + Returns product of parsing. Returned value is result of parsing + of the document. The type of this result depends on internal + representation in derived parser (but it must be derived from wxObject!). + + See wxHtmlWinParser for details. + */ + virtual wxObject* GetProduct(); + + /** + Returns pointer to the source being parsed. + */ + wxString* GetSource(); + + /** + Setups the parser for parsing the @e source string. (Should be overridden + in derived class) + */ + virtual void InitParser(const wxString& source); + + /** + Opens given URL and returns @c wxFSFile object that can be used to read data + from it. This method may return @NULL in one of two cases: either the URL doesn't + point to any valid resource or the URL is blocked by overridden implementation + of @e OpenURL in derived class. + + @param type + Indicates type of the resource. Is one of: + + wxHTML_URL_PAGE + + + Opening a HTML page. + + wxHTML_URL_IMAGE + + + Opening an image. + + wxHTML_URL_OTHER + + + Opening a resource that doesn't fall into + any other category. + + @param url + URL being opened. + */ + virtual wxFSFile* OpenURL(wxHtmlURLType type, + const wxString& url); + + /** + Proceeds parsing of the document. This is end-user method. You can simply + call it when you need to obtain parsed output (which is parser-specific) + + The method does these things: + + calls @ref initparser() InitParser(source) + calls DoParsing() + calls GetProduct() + calls DoneParser() + returns value returned by GetProduct + + You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly. + */ + wxObject* Parse(const wxString& source); + + /** + Restores parser's state before last call to + PushTagHandler(). + */ + void PopTagHandler(); + + /** + Forces the handler to handle additional tags + (not returned by wxHtmlTagHandler::GetSupportedTags). + The handler should already be added to this parser. + + @param handler + the handler + + @param tags + List of tags (in same format as GetSupportedTags's return value). The parser + will redirect these tags to handler (until call to PopTagHandler). + */ + void PushTagHandler(wxHtmlTagHandler* handler, + const wxString& tags); + + /** + Sets the virtual file system that will be used to request additional + files. (For example @c IMG tag handler requests wxFSFile with the + image data.) + */ +#define void SetFS(wxFileSystem fs) /* implementation is private */ + + /** + Call this function to interrupt parsing from a tag handler. No more tags + will be parsed afterward. This function may only be called from + Parse() or any function called + by it (i.e. from tag handlers). + */ + void StopParsing(); +}; diff --git a/interface/html/htmltag.h b/interface/html/htmltag.h new file mode 100644 index 0000000000..a16681a861 --- /dev/null +++ b/interface/html/htmltag.h @@ -0,0 +1,135 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmltag.h +// Purpose: documentation for wxHtmlTag class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlTag + @headerfile htmltag.h wx/html/htmltag.h + + This class represents a single HTML tag. + It is used by @ref overview_handlers "tag handlers". + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlTag +{ +public: + /** + Constructor. You will probably never have to construct a wxHtmlTag object + yourself. Feel free to ignore the constructor parameters. + Have a look at src/html/htmlpars.cpp if you're interested in creating it. + */ + wxHtmlTag(wxHtmlTag * parent, const wxString& source, int pos, + int end_pos, wxHtmlTagsCache* cache, + wxHtmlEntitiesParser * entParser); + + /** + Returns a string containing all parameters. + + Example : tag contains @c FONT SIZE=+2 COLOR="#000000". Call to + tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000". + */ + const wxString GetAllParams(); + + /** + Returns beginning position of the text @e between this tag and paired + ending tag. + See explanation (returned position is marked with '|'): + */ + int GetBeginPos(); + + /** + Returns ending position of the text @e between this tag and paired + ending tag. + See explanation (returned position is marked with '|'): + */ + int GetEndPos1(); + + /** + Returns ending position 2 of the text @e between this tag and paired + ending tag. + See explanation (returned position is marked with '|'): + */ + int GetEndPos2(); + + /** + Returns tag's name. The name is always in uppercase and it doesn't contain + '' or '/' characters. (So the name of @c FONT SIZE=+2 tag is "FONT" + and name of @c /table is "TABLE") + */ + wxString GetName(); + + /** + Returns the value of the parameter. You should check whether the + parameter exists or not (use wxHtmlTag::HasParam) first. + + @param par + The parameter's name. + + @param with_quotes + @true if you want to get quotes as well. See example. + */ + wxString GetParam(const wxString& par, bool with_quotes = @false); + + /** + Interprets tag parameter @e par as colour specification and saves its value + into wxColour variable pointed by @e clr. + + Returns @true on success and @false if @e par is not colour specification or + if the tag has no such parameter. + */ + bool GetParamAsColour(const wxString& par, wxColour * clr); + + /** + Interprets tag parameter @e par as an integer and saves its value + into int variable pointed by @e value. + + Returns @true on success and @false if @e par is not an integer or + if the tag has no such parameter. + */ + bool GetParamAsInt(const wxString& par, int * value); + + /** + Returns @true if this tag is paired with ending tag, @false otherwise. + + See the example of HTML document: + In this example tags HTML and BODY have ending tags, first P and BR + doesn't have ending tag while the second P has. The third P tag (which + is ending itself) of course doesn't have ending tag. + */ + bool HasEnding(); + + /** + Returns @true if the tag has a parameter of the given name. + Example : @c FONT SIZE=+2 COLOR="#FF00FF" has two parameters named + "SIZE" and "COLOR". + + @param par + the parameter you're looking for. + */ + bool HasParam(const wxString& par); + + /** + This method scans the given parameter. Usage is exactly the same as sscanf's + usage except that you don't pass a string but a parameter name as the first + argument + and you can only retrieve one value (i.e. you can use only one "%" element + in @e format). + + @param par + The name of the tag you want to query + + @param format + scanf()-like format string. + + @param value + pointer to a variable to store the value in + */ + wxString ScanParam(const wxString& par, const wxChar * format, + void * value); +}; diff --git a/interface/html/htmlwin.h b/interface/html/htmlwin.h new file mode 100644 index 0000000000..37299ef9aa --- /dev/null +++ b/interface/html/htmlwin.h @@ -0,0 +1,464 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmlwin.h +// Purpose: documentation for wxHtmlWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlWindow + @headerfile htmlwin.h wx/html/htmlwin.h + + wxHtmlWindow is probably the only class you will directly use + unless you want to do something special (like adding new tag + handlers or MIME filters). + + The purpose of this class is to display HTML pages (either local + file or downloaded via HTTP protocol) in a window. The width + of the window is constant - given in the constructor - and virtual height + is changed dynamically depending on page size. + Once the window is created you can set its content by calling + @ref wxHtmlWindow::setpage SetPage(text), + @ref wxHtmlWindow::loadpage LoadPage(filename) or + wxHtmlWindow::LoadFile. + + @beginStyleTable + @style{wxHW_SCROLLBAR_NEVER}: + Never display scrollbars, not even when the page is larger than the + window. + @style{wxHW_SCROLLBAR_AUTO}: + Display scrollbars only if page's size exceeds window's size. + @style{wxHW_NO_SELECTION}: + Don't allow the user to select text. + @endStyleTable + + @library{wxhtml} + @category{html} + + @seealso + wxHtmlLinkEvent, wxHtmlCellEvent +*/ +class wxHtmlWindow : public wxScrolledWindow +{ +public: + //@{ + /** + Constructor. The parameters are the same as for the wxScrolledWindow + constructor. + + @param style + Window style. See wxHtmlWindow. + */ + wxHtmlWindow(); + wxHtmlWindow(wxWindow parent, wxWindowID id = -1, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxHW_DEFAULT_STYLE, + const wxString& name = "htmlWindow"); + //@} + + /** + Adds @ref overview_filters "input filter" to the static list of available + filters. These filters are present by default: + + @c text/html MIME type + @c image/* MIME types + Plain Text filter (this filter is used if no other filter matches) + */ + static void AddFilter(wxHtmlFilter filter); + + /** + Appends HTML fragment to currently displayed text and refreshes the window. + + @param source + HTML code fragment + + @returns @false if an error occurred, @true otherwise. + */ + bool AppendToPage(const wxString& source); + + /** + Returns pointer to the top-level container. + + See also: @ref overview_cells "Cells Overview", + @ref overview_printing "Printing Overview" + */ + wxHtmlContainerCell* GetInternalRepresentation(); + + /** + Returns anchor within currently opened page + (see wxHtmlWindow::GetOpenedPage). + If no page is opened or if the displayed page wasn't + produced by call to LoadPage, empty string is returned. + */ + wxString GetOpenedAnchor(); + + /** + Returns full location of the opened page. If no page is opened or if the + displayed page wasn't + produced by call to LoadPage, empty string is returned. + */ + wxString GetOpenedPage(); + + /** + Returns title of the opened page or wxEmptyString if current page does not + contain @c TITLE tag. + */ + wxString GetOpenedPageTitle(); + + /** + Returns the related frame. + */ + wxFrame* GetRelatedFrame(); + + /** + Moves back to the previous page. (each page displayed using + LoadPage() is stored in history list.) + */ + bool HistoryBack(); + + /** + Returns @true if it is possible to go back in the history (i.e. HistoryBack() + won't fail). + */ + bool HistoryCanBack(); + + /** + Returns @true if it is possible to go forward in the history (i.e. HistoryBack() + won't fail). + */ + bool HistoryCanForward(); + + /** + Clears history. + */ + void HistoryClear(); + + /** + Moves to next page in history. + */ + bool HistoryForward(); + + /** + Loads HTML page from file and displays it. + + @returns @false if an error occurred, @true otherwise + + @sa LoadPage() + */ + virtual bool LoadFile(const wxFileName& filename); + + /** + Unlike SetPage this function first loads HTML page from @e location + and then displays it. See example: + + @param location + The address of document. See wxFileSystem for details on address format and + behaviour of "opener". + + @returns @false if an error occurred, @true otherwise + + @sa LoadFile() + */ + virtual bool LoadPage(const wxString& location); + + /** + This method is called when a mouse button is clicked inside wxHtmlWindow. + + The default behaviour is to emit a wxHtmlCellEvent + and, if the event was not processed or skipped, call + OnLinkClicked() if the cell contains an + hypertext link. + + Overloading this method is deprecated; intercept the event instead. + + @param cell + The cell inside which the mouse was clicked, always a simple + (i.e. non-container) cell + + @param x, y + The logical coordinates of the click point + + @param event + The mouse event containing other information about the click + + @returns @true if a link was clicked, @false otherwise. + */ + virtual bool OnCellClicked(wxHtmlCell cell, wxCoord x, wxCoord y, + const wxMouseEvent& event); + + /** + This method is called when a mouse moves over an HTML cell. + Default behaviour is to emit a wxHtmlCellEvent. + Overloading this method is deprecated; intercept the event instead. + + @param cell + The cell inside which the mouse is currently, always a simple + (i.e. non-container) cell + + @param x, y + The logical coordinates of the click point + */ + virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x, + wxCoord y); + + /** + Called when user clicks on hypertext link. Default behaviour is to emit a + wxHtmlLinkEvent and, if the event was not processed + or skipped, call LoadPage() and do nothing else. + Overloading this method is deprecated; intercept the event instead. + + Also see wxHtmlLinkInfo. + */ + virtual void OnLinkClicked(const wxHtmlLinkInfo& link); + + /** + Called when an URL is being opened (either when the user clicks on a link or + an image is loaded). The URL will be opened only if OnOpeningURL returns + @c wxHTML_OPEN. This method is called by + wxHtmlParser::OpenURL. + You can override OnOpeningURL to selectively block some + URLs (e.g. for security reasons) or to redirect them elsewhere. Default + behaviour is to always return @c wxHTML_OPEN. + + @param type + Indicates type of the resource. Is one of + + + wxHTML_URL_PAGE + + + Opening a HTML page. + + wxHTML_URL_IMAGE + + + Opening an image. + + wxHTML_URL_OTHER + + + Opening a resource that doesn't fall into + any other category. + + @param url + URL being opened. + + @param redirect + Pointer to wxString variable that must be filled with an + URL if OnOpeningURL returns wxHTML_REDIRECT. + */ + virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type, + const wxString& url, + wxString * redirect); + + /** + Called on parsing @c TITLE tag. + */ + virtual void OnSetTitle(const wxString& title); + + /** + This reads custom settings from wxConfig. It uses the path 'path' + if given, otherwise it saves info into currently selected path. + The values are stored in sub-path @c wxHtmlWindow + + Read values: all things set by SetFonts, SetBorders. + + @param cfg + wxConfig from which you want to read the configuration. + + @param path + Optional path in config tree. If not given current path is used. + */ + virtual void ReadCustomization(wxConfigBase cfg, + wxString path = wxEmptyString); + + /** + Selects all text in the window. + + @sa SelectLine(), SelectWord() + */ + void SelectAll(); + + /** + Selects the line of text that @e pos points at. Note that @e pos + is relative to the top of displayed page, not to window's origin, use + wxScrolledWindow::CalcUnscrolledPosition + to convert physical coordinate. + + @sa SelectAll(), SelectWord() + */ + void SelectLine(const wxPoint& pos); + + /** + Selects the word at position @e pos. Note that @e pos + is relative to the top of displayed page, not to window's origin, use + wxScrolledWindow::CalcUnscrolledPosition + to convert physical coordinate. + + @sa SelectAll(), SelectLine() + */ + void SelectWord(const wxPoint& pos); + + /** + Returns current selection as plain text. Returns empty string if no text + is currently selected. + */ + wxString SelectionToText(); + + /** + This function sets the space between border of window and HTML contents. See + image: + + @param b + indentation from borders in pixels + */ + void SetBorders(int b); + + /** + This function sets font sizes and faces. + + @param normal_face + This is face name for normal (i.e. non-fixed) font. + It can be either empty string (then the default face is chosen) or + platform-specific face name. Examples are "helvetica" under Unix or + "Times New Roman" under Windows. + + @param fixed_face + The same thing for fixed face ( TT../TT ) + + @param sizes + This is an array of 7 items of int type. + The values represent size of font with HTML size from -2 to +4 + ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes + is @NULL. + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = @NULL); + + /** + Sets HTML page and display it. This won't @b load the page!! + It will display the @e source. See example: + If you want to load a document from some location use + LoadPage() instead. + + @param source + The HTML document source to be displayed. + + @returns @false if an error occurred, @true otherwise. + */ + bool SetPage(const wxString& source); + + /** + Sets the frame in which page title will be displayed. @e format is format of + frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This + %s is substituted with HTML page title. + */ + void SetRelatedFrame(wxFrame* frame, const wxString& format); + + /** + @b After calling SetRelatedFrame(), + this sets statusbar slot where messages will be displayed. + (Default is -1 = no messages.) + + @param bar + statusbar slot number (0..n) + */ + void SetRelatedStatusBar(int bar); + + /** + Returns content of currently displayed page as plain text. + */ + wxString ToText(); + + /** + Saves custom settings into wxConfig. It uses the path 'path' + if given, otherwise it saves info into currently selected path. + Regardless of whether the path is given or not, the function creates sub-path + @c wxHtmlWindow. + + Saved values: all things set by SetFonts, SetBorders. + + @param cfg + wxConfig to which you want to save the configuration. + + @param path + Optional path in config tree. If not given, the current path is used. + */ + virtual void WriteCustomization(wxConfigBase cfg, + wxString path = wxEmptyString); +}; + + +/** + @class wxHtmlLinkEvent + @headerfile htmlwin.h wx/html/htmlwin.h + + This event class is used for the events generated by wxHtmlWindow. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlLinkEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxHyperlinkEvent(int id, const wxHtmlLinkInfo & linkinfo); + + /** + Returns the wxHtmlLinkInfo which contains info about the cell clicked and the + hyperlink it contains. + */ + const wxHtmlLinkInfo GetLinkInfo(); +}; + + +/** + @class wxHtmlCellEvent + @headerfile htmlwin.h wx/html/htmlwin.h + + This event class is used for the events generated by wxHtmlWindow. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlCellEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxHtmlCellEvent(wxEventType commandType, int id, + wxHtmlCell * cell, + const wxPoint & point); + + /** + Returns the wxHtmlCellEvent associated with the event. + */ + wxHtmlCell * GetCell(); + + /** + Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously + been called; + @false otherwise. + */ + bool GetLinkClicked(); + + /** + Returns the wxPoint associated with the event. + */ + wxPoint GetPoint(); + + /** + Call this function with @c linkclicked set to @true if the cell which has + been clicked contained a link or + @false otherwise (which is the default). With this function the event handler + can return info to the + wxHtmlWindow which sent the event. + */ + bool SetLinkClicked(bool linkclicked); +}; diff --git a/interface/html/htmprint.h b/interface/html/htmprint.h new file mode 100644 index 0000000000..1f0bb515a9 --- /dev/null +++ b/interface/html/htmprint.h @@ -0,0 +1,350 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmprint.h +// Purpose: documentation for wxHtmlDCRenderer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlDCRenderer + @headerfile htmprint.h wx/html/htmprint.h + + This class can render HTML document into a specified area of a DC. You can use + it + in your own printing code, although use of wxHtmlEasyPrinting + or wxHtmlPrintout is strongly recommended. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlDCRenderer : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlDCRenderer(); + + /** + Returns the height of the HTML text. This is important if area height (see + wxHtmlDCRenderer::SetSize) + is smaller that total height and thus the page cannot fit into it. In that case + you're supposed to + call Render() as long as its return value is smaller than GetTotalHeight's. + */ + int GetTotalHeight(); + + /** + Renders HTML text to the DC. + + @param x,y + position of upper-left corner of printing rectangle (see SetSize) + + @param from + y-coordinate of the very first visible cell + + @param dont_render + if @true then this method only returns y coordinate of the next page + and does not output anything + */ + int Render(int x, int y, int from = 0, int dont_render = @false); + + /** + Assign DC instance to the renderer. + + @e 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.) + */ +#define void SetDC(wxDC* dc, double pixel_scale = 1.0) /* implementation is private */ + + /** + Sets fonts. See wxHtmlWindow::SetFonts for + detailed description. + + See also SetSize(). + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = @NULL); + + /** + Assign text to the renderer. Render() then draws + the text onto DC. + + @param html + HTML text. This is not a filename. + + @param basepath + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. + + @param isdir + @false if basepath is filename, @true if it is directory name + (see wxFileSystem for detailed explanation) + */ + void SetHtmlText(const wxString& html, + const wxString& basepath = wxEmptyString, + bool isdir = @true); + + /** + Set size of output rectangle, in pixels. Note that you @b can't change + width of the rectangle between calls to wxHtmlDCRenderer::Render! + (You can freely change height.) + */ + void SetSize(int width, int height); +}; + + +/** + @class wxHtmlEasyPrinting + @headerfile htmprint.h wx/html/htmprint.h + + This class provides very simple interface to printing + architecture. It allows you to print HTML documents using + only a few commands. + + @library{wxhtml} + @category{html} +*/ +class wxHtmlEasyPrinting : public wxObject +{ +public: + /** + Constructor. + + @param name + Name of the printing object. Used by preview frames and setup dialogs. + + @param parentWindow + pointer to the window that will own the preview frame and setup dialogs. May be + @NULL. + */ + wxHtmlEasyPrinting(const wxString& name = "Printing", + wxWindow* parentWindow = @NULL); + + /** + Returns a pointer to wxPageSetupDialogData instance used by + this class. You can set its parameters (via SetXXXX methods). + */ + wxPageSetupDialogData* GetPageSetupData(); + + /** + Gets the parent window for dialogs. + */ + wxWindow* GetParentWindow(); + + /** + Returns pointer to wxPrintData instance used by this class. You can + set its parameters (via SetXXXX methods). + */ + wxPrintData* GetPrintData(); + + /** + Display page setup dialog and allows the user to modify settings. + */ + void PageSetup(); + + /** + Preview HTML file. + + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + */ + bool PreviewFile(const wxString& htmlfile); + + /** + Preview HTML text (not file!). + + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + + @param htmltext + HTML text. + + @param basepath + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. + */ + bool PreviewText(const wxString& htmltext, + const wxString& basepath = wxEmptyString); + + /** + Print HTML file. + + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + */ + bool PrintFile(const wxString& htmlfile); + + /** + Print HTML text (not file!). + + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + + @param htmltext + HTML text. + + @param basepath + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. + */ + bool PrintText(const wxString& htmltext, + const wxString& basepath = wxEmptyString); + + /** + Sets fonts. See wxHtmlWindow::SetFonts for + detailed description. + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = @NULL); + + /** + Set page footer. The following macros can be used inside it: + + @DATE@ is replaced by the current date in default format + @PAGENUM@ is replaced by page number + @PAGESCNT@ is replaced by total number of pages + @TIME@ is replaced by the current time in default format + @TITLE@ is replaced with the title of the document + + @param footer + HTML text to be used as footer. + + @param pg + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + */ + void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); + + /** + Set page header. The following macros can be used inside it: + + @DATE@ is replaced by the current date in default format + @PAGENUM@ is replaced by page number + @PAGESCNT@ is replaced by total number of pages + @TIME@ is replaced by the current time in default format + @TITLE@ is replaced with the title of the document + + @param header + HTML text to be used as header. + + @param pg + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + */ + void SetHeader(const wxString& header, int pg = wxPAGE_ALL); + + /** + Sets the parent window for dialogs. + */ + void SetParentWindow(wxWindow* window); +}; + + +/** + @class wxHtmlPrintout + @headerfile htmprint.h wx/html/htmprint.h + + This class serves as printout class for HTML documents. + + @library{wxhtml} + @category{html} +*/ +class wxHtmlPrintout : public wxPrintout +{ +public: + /** + Constructor. + */ + wxHtmlPrintout(const wxString& title = "Printout"); + + /** + Adds a filter to the static list of filters for wxHtmlPrintout. See + wxHtmlFilter for + further information. + */ + static void AddFilter(wxHtmlFilter* filter); + + /** + Sets fonts. See wxHtmlWindow::SetFonts for + detailed description. + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = @NULL); + + /** + Set page footer. The following macros can be used inside it: + + @DATE@ is replaced by the current date in default format + @PAGENUM@ is replaced by page number + @PAGESCNT@ is replaced by total number of pages + @TIME@ is replaced by the current time in default format + @TITLE@ is replaced with the title of the document + + @param footer + HTML text to be used as footer. + + @param pg + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + */ + void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); + + /** + Set page header. The following macros can be used inside it: + + @DATE@ is replaced by the current date in default format + @PAGENUM@ is replaced by page number + @PAGESCNT@ is replaced by total number of pages + @TIME@ is replaced by the current time in default format + @TITLE@ is replaced with the title of the document + + @param header + HTML text to be used as header. + + @param pg + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + */ + void SetHeader(const wxString& header, int pg = wxPAGE_ALL); + + /** + Prepare the class for printing this HTML @b file. The file may be located on + any virtual file system or it may be normal file. + */ + void SetHtmlFile(const wxString& htmlfile); + + /** + Prepare the class for printing this HTML text. + + @param html + HTML text. (NOT file!) + + @param basepath + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. + + @param isdir + @false if basepath is filename, @true if it is directory name + (see wxFileSystem for detailed explanation) + */ + void SetHtmlText(const wxString& html, + const wxString& basepath = wxEmptyString, + bool isdir = @true); + + /** + Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space + between text and header and/or footer + */ + void SetMargins(float top = 25.2, float bottom = 25.2, + float left = 25.2, + float right = 25.2, + float spaces = 5); +}; diff --git a/interface/html/winpars.h b/interface/html/winpars.h new file mode 100644 index 0000000000..cbe7197d61 --- /dev/null +++ b/interface/html/winpars.h @@ -0,0 +1,314 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/winpars.h +// Purpose: documentation for wxHtmlTagsModule class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlTagsModule + @headerfile winpars.h wx/html/winpars.h + + This class provides easy way of filling wxHtmlWinParser's table of + tag handlers. It is used almost exclusively together with the set of + @ref overview_handlers "TAGS_MODULE_* macros" + + @library{wxhtml} + @category{FIXME} + + @seealso + @ref overview_handlers "Tag Handlers", wxHtmlTagHandler, wxHtmlWinTagHandler, +*/ +class wxHtmlTagsModule : public wxModule +{ +public: + /** + You must override this method. In most common case its body consists + only of lines of the following type: + I recommend using the @b TAGS_MODULE_* macros. + + @param parser + Pointer to the parser that requested tables filling. + */ + virtual void FillHandlersTable(wxHtmlWinParser parser); +}; + + +/** + @class wxHtmlWinTagHandler + @headerfile winpars.h wx/html/winpars.h + + This is basically wxHtmlTagHandler except that + it is extended with protected member m_WParser pointing to + the wxHtmlWinParser object (value of this member is identical + to wxHtmlParser's m_Parser). + + @library{wxhtml} + @category{html} +*/ +class wxHtmlWinTagHandler : public wxHtmlTagHandler +{ +public: + /** + @b wxHtmlWinParser* m_WParser + + Value of this attribute is identical to value of m_Parser. The only different + is that m_WParser points to wxHtmlWinParser object while m_Parser + points to wxHtmlParser object. (The same object, but overcast.) + */ +}; + + +/** + @class wxHtmlWinParser + @headerfile winpars.h wx/html/winpars.h + + This class is derived from wxHtmlParser and + its main goal is to parse HTML input so that it can be displayed in + wxHtmlWindow. It uses a special + wxHtmlWinTagHandler. + + @library{wxhtml} + @category{html} + + @seealso + @ref overview_handlers "Handlers overview" +*/ +class wxHtmlWinParser : public wxHtmlParser +{ +public: + //@{ + /** + Constructor. Don't use the default one, use constructor with + @e wndIface parameter (@e wndIface is a pointer to interface object for + the associated wxHtmlWindow or other HTML rendering + window such as wxHtmlListBox). + */ + wxHtmlWinParser(); + wxHtmlWinParser(wxHtmlWindowInterface wndIface); + //@} + + /** + Adds module to the list of wxHtmlWinParser tag handler. + */ + static void AddModule(wxHtmlTagsModule module); + + /** + Closes the container, sets actual container to the parent one + and returns pointer to it (see Overview). + */ + wxHtmlContainerCell* CloseContainer(); + + /** + Creates font based on current setting (see + SetFontSize(), + SetFontBold(), + SetFontItalic(), + SetFontFixed(), + wxHtmlWinParser::SetFontUnderlined) + and returns pointer to it. + If the font was already created only a pointer is returned. + */ + virtual wxFont* CreateCurrentFont(); + + /** + Returns actual text colour. + */ + const wxColour GetActualColor(); + + /** + Returns default horizontal alignment. + */ + int GetAlign(); + + /** + Returns (average) char height in standard font. It is used as DC-independent + metrics. + + @b Note: This function doesn't return the @e actual height. If you want to + know the height of the current font, call @c GetDC - GetCharHeight(). + */ + int GetCharHeight(); + + /** + Returns average char width in standard font. It is used as DC-independent + metrics. + + @b Note: This function doesn't return the @e actual width. If you want to + know the height of the current font, call @c GetDC - GetCharWidth() + */ + int GetCharWidth(); + + /** + Returns pointer to the currently opened container (see Overview). + Common use: + */ + wxHtmlContainerCell* GetContainer(); + + /** + Returns pointer to the DC used during parsing. + */ +#define wxDC* GetDC() /* implementation is private */ + + /** + Returns wxEncodingConverter class used + to do conversion between @ref getinputencoding() "input encoding" + and @ref getoutputencoding() "output encoding". + */ + wxEncodingConverter * GetEncodingConverter(); + + /** + Returns @true if actual font is bold, @false otherwise. + */ + int GetFontBold(); + + /** + Returns actual font face name. + */ + wxString GetFontFace(); + + /** + Returns @true if actual font is fixed face, @false otherwise. + */ + int GetFontFixed(); + + /** + Returns @true if actual font is italic, @false otherwise. + */ + int GetFontItalic(); + + /** + Returns actual font size (HTML size varies from -2 to +4) + */ + int GetFontSize(); + + /** + Returns @true if actual font is underlined, @false otherwise. + */ + int GetFontUnderlined(); + + /** + Returns input encoding. + */ + wxFontEncoding GetInputEncoding(); + + /** + Returns actual hypertext link. (This value has a non-empty + @ref wxHtmlLinkInfo::gethref Href string + if the parser is between @c A and @c /A tags, + wxEmptyString otherwise.) + */ + const wxHtmlLinkInfo GetLink(); + + /** + Returns the colour of hypertext link text. + */ + const wxColour GetLinkColor(); + + /** + Returns output encoding, i.e. closest match to document's input encoding + that is supported by operating system. + */ + wxFontEncoding GetOutputEncoding(); + + /** + Returns associated window (wxHtmlWindow). This may be @NULL! (You should always + test if it is non-@NULL. For example @c TITLE handler sets window + title only if some window is associated, otherwise it does nothing) + */ + wxHtmlWindow* GetWindow(); + + /** + Opens new container and returns pointer to it (see Overview). + */ + wxHtmlContainerCell* OpenContainer(); + + /** + Sets actual text colour. Note: this DOESN'T change the colour! + You must create wxHtmlColourCell yourself. + */ + void SetActualColor(const wxColour& clr); + + /** + Sets default horizontal alignment (see + wxHtmlContainerCell::SetAlignHor.) + Alignment of newly opened container is set to this value. + */ + void SetAlign(int a); + + /** + Allows you to directly set opened container. This is not recommended - you + should use OpenContainer + wherever possible. + */ + wxHtmlContainerCell* SetContainer(wxHtmlContainerCell * c); + + /** + Sets the DC. This must be called before wxHtmlParser::Parse! + @e 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.) + */ +#define virtual void SetDC(wxDC dc, double pixel_scale = 1.0) /* implementation is private */ + + /** + Sets bold flag of actualfont. @e x is either @true of @false. + */ + void SetFontBold(int x); + + /** + Sets current font face to @e face. This affects either fixed size + font or proportional, depending on context (whether the parser is + inside @c TT tag or not). + */ + void SetFontFace(const wxString& face); + + /** + Sets fixed face flag of actualfont. @e x is either @true of @false. + */ + void SetFontFixed(int x); + + /** + Sets italic flag of actualfont. @e x is either @true of @false. + */ + void SetFontItalic(int x); + + /** + Sets actual font size (HTML size varies from 1 to 7) + */ + void SetFontSize(int s); + + /** + Sets underlined flag of actualfont. @e x is either @true of @false. + */ + void SetFontUnderlined(int x); + + /** + Sets fonts. See wxHtmlWindow::SetFonts for + detailed description. + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = @NULL); + + /** + Sets input encoding. The parser uses this information to build conversion + tables from document's encoding to some encoding supported by operating + system. + */ + void SetInputEncoding(wxFontEncoding enc); + + /** + Sets actual hypertext link. Empty link is represented + by wxHtmlLinkInfo with @e Href equal + to wxEmptyString. + */ + void SetLink(const wxHtmlLinkInfo& link); + + /** + Sets colour of hypertext link. + */ + void SetLinkColor(const wxColour& clr); +}; diff --git a/interface/htmllbox.h b/interface/htmllbox.h new file mode 100644 index 0000000000..72e185f7b3 --- /dev/null +++ b/interface/htmllbox.h @@ -0,0 +1,245 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: htmllbox.h +// Purpose: documentation for wxHtmlListBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlListBox + @wxheader{htmllbox.h} + + wxHtmlListBox is an implementation of wxVListBox which + shows HTML content in the listbox rows. This is still an abstract base class + and you will need to derive your own class from it (see htlbox sample for the + example) but you will only need to override a single + wxHtmlListBox::OnGetItem function. + + @library{wxhtml} + @category{ctrl} + @appearance{htmllistbox.png} + + @seealso + wxSimpleHtmlListBox +*/ +class wxHtmlListBox : public wxVListBox +{ +public: + //@{ + /** + Default constructor, you must call Create() + later. + */ + wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxHtmlListBoxNameStr); + wxHtmlListBox(); + //@} + + /** + Destructor cleans up whatever resources we use. + */ + ~wxHtmlListBox(); + + /** + Creates the control and optionally sets the initial number of items in it + (it may also be set or changed later with + wxVListBox::SetItemCount). + + There are no special styles defined for wxHtmlListBox, in particular the + wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here. + + Returns @true on success or @false if the control couldn't be created + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxHtmlListBoxNameStr); + + //@{ + /** + Returns the wxFileSystem used by the HTML parser of + this object. The file system object is used to resolve the paths in HTML + fragments displayed in the control and you should use + wxFileSystem::ChangePathTo if you use + relative paths for the images or other resources embedded in your HTML. + */ + wxFileSystem GetFileSystem(); + const wxFileSystem GetFileSystem(); + //@} + + /** + This virtual function may be overridden to change the appearance of the + background of the selected cells in the same way as + GetSelectedTextColour(). + + It should be rarely, if ever, used because + wxVListBox::SetSelectionBackground allows to + change the selection background for all cells at once and doing anything more + fancy is probably going to look strangely. + + @sa GetSelectedTextColour() + */ + wxColour GetSelectedTextBgColour(const wxColour& colBg); + + /** + This virtual function may be overridden to customize the appearance of the + selected cells. It is used to determine how the colour @e 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. + + @sa GetSelectedTextBgColour(), + wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour + */ + wxColour GetSelectedTextColour(const wxColour& colFg); + + /** + This method must be implemented in the derived class and should return + the body (i.e. without @c html nor @c body tags) of the HTML fragment + for the given item. + + Note that this function should always return a text fragment for the @e n item + which renders with the same height both when it is selected and when it's not: + i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to + make the items appear differently when they are selected, then you should make + sure + that the returned HTML fragment will render with the same height or else you'll + see some artifacts when the user selects an item. + */ + wxString OnGetItem(size_t n); + + /** + This function may be overridden to decorate HTML returned by + OnGetItem(). + */ + wxString OnGetItemMarkup(size_t n); + + /** + Called when the user clicks on hypertext link. Does nothing by default. + Overloading this method is deprecated; intercept the event instead. + + @param n + Index of the item containing the link. + + @param link + Description of the link. + + @sa See also wxHtmlLinkInfo. + */ + virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link); +}; + + +/** + @class wxSimpleHtmlListBox + @wxheader{htmllbox.h} + + wxSimpleHtmlListBox is an implementation of wxHtmlListBox which + shows HTML content in the listbox rows. + + Unlike wxHtmlListBox, this is not an abstract class and thus it + has the advantage that you can use it without deriving your own class from it. + However, it also has the disadvantage that this is not a virtual control and + thus it's not + well-suited for those cases where you need to show a huge number of items: + every time you + add/insert a string, it will be stored internally and thus will take memory. + + The interface exposed by wxSimpleHtmlListBox fully implements the + wxControlWithItems interface, thus you should refer to + wxControlWithItems's documentation for the API reference + for adding/removing/retrieving items in the listbox. + Also note that the wxVListBox::SetItemCount function is + @c protected in wxSimpleHtmlListBox's context so that you cannot call it + directly, + wxSimpleHtmlListBox will do it for you. + + Note: in case you need to append a lot of items to the control at once, make + sure to use the + @ref wxControlWithItems::append "Append(const wxArrayString )" function. + + Thus the only difference between a wxListBox and a wxSimpleHtmlListBox + is that the latter stores strings which can contain HTML fragments (see the + list of + @ref overview_htmltagssupported "tags supported by wxHTML"). + + Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain + the @c html + or @c body tags. + + @beginStyleTable + @style{wxHLB_DEFAULT_STYLE}: + The default style: wxBORDER_SUNKEN + @style{wxHLB_MULTIPLE}: + Multiple-selection list: the user can toggle multiple items on and + off. + @endStyleTable + + @library{wxhtml} + @category{ctrl} + @appearance{simplehtmllistbox.png} + + @seealso + wxSimpleHtmlListBox::Create +*/ +class wxSimpleHtmlListBox : public wxHtmlListBox +{ +public: + //@{ + /** + Default constructor, you must call Create() + later. + */ + wxHtmlListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = @NULL, + long style = wxHLB_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "simpleHtmlListBox"); + wxHtmlListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = wxHLB_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "simpleHtmlListBox"); + See also +wxSimpleHtmlListBox::Create + + wxSimpleHtmlListBox(); + //@} + + /** + Frees the array of stored items and relative client data. + */ + ~wxSimpleHtmlListBox(); + + //@{ + /** + Creates the HTML listbox for two-step construction. + See wxSimpleHtmlListBox() for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, + const wxString choices[] = @NULL, + long style = wxHLB_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "simpleHtmlListBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = wxHLB_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "simpleHtmlListBox"); + //@} +}; diff --git a/interface/hyperlink.h b/interface/hyperlink.h new file mode 100644 index 0000000000..7506b08643 --- /dev/null +++ b/interface/hyperlink.h @@ -0,0 +1,193 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: hyperlink.h +// Purpose: documentation for wxHyperlinkEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHyperlinkEvent + @wxheader{hyperlink.h} + + This event class is used for the events generated by + wxHyperlinkCtrl. + + @library{wxadv} + @category{FIXME} +*/ +class wxHyperlinkEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxHyperlinkEvent(wxObject * generator, int id, + const wxString & url); + + /** + Returns the URL of the hyperlink where the user has just clicked. + */ +#define wxString GetURL() /* implementation is private */ + + /** + Sets the URL associated with the event. + */ +#define void SetURL(const wxString & url) /* implementation is private */ +}; + + +/** + @class wxHyperlinkCtrl + @wxheader{hyperlink.h} + + This class shows a static text element which links to an URL. + Appearance and behaviour is completely customizable. In fact, when the user + clicks on the hyperlink, a wxHyperlinkEvent is + sent but if that event is not handled (or it's skipped; see + wxEvent::Skip), then a call to + wxLaunchDefaultBrowser is done with the + hyperlink's URL. + + Note that standard wxWindow functions like wxWindow::SetBackgroundColour, + wxWindow::SetFont, wxWindow::SetCursor, wxWindow::SetLabel can be used to customize appearance of the hyperlink. + + @beginStyleTable + @style{wxHL_ALIGN_LEFT}: + Align the text to the left. + @style{wxHL_ALIGN_RIGHT}: + Align the text to the right. + @style{wxHL_ALIGN_CENTRE}: + Center the text (horizontally). + @style{wxHL_CONTEXTMENU}: + Pop up a context menu when the hyperlink is right-clicked. The + context menu contains a "Copy URL" menu item which is automatically + handled by the hyperlink and which just copies in the clipboard the + URL (not the label) of the control. + @style{wxHL_DEFAULT_STYLE}: + The default style for wxHyperlinkCtrl: + wxBORDER_NONE|wxHL_CONTEXTMENU|wxHL_ALIGN_CENTRE. + @endStyleTable + + @library{wxadv} + @category{ctrl} + @appearance{hyperlinkctrl.png} + + @seealso + wxURL, wxHyperlinkEvent +*/ +class wxHyperlinkCtrl : public wxControl +{ +public: + /** + Creates the hyperlink control. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. A value of wxID_ANY indicates a default value. + + @param label + The label of the hyperlink. + + @param url + The URL associated with the given label. + + @param pos + Window position. + + @param size + Window size. If the wxDefaultSize is specified then the window is sized + appropriately. + + @param style + Window style. See wxHyperlinkCtrl. + + @param validator + Window validator. + + @param name + Window name. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString & label, + const wxString & url, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style, + const wxString& name = "hyperlink"); + + /** + Returns the colour used to print the label of the hyperlink when the mouse is + over the control. + */ + wxColour GetHoverColour(); + + /** + Returns the colour used to print the label when the link has never been clicked + before + (i.e. the link has not been @e visited) and the mouse is not over the control. + */ + wxColour GetNormalColour(); + + /** + Returns the URL associated with the hyperlink. + */ +#define wxString GetURL() /* implementation is private */ + + /** + Returns @true if the hyperlink has already been clicked by the user at least + one time. + */ + bool GetVisited(); + + /** + Returns the colour used to print the label when the mouse is not over the + control + and the link has already been clicked before (i.e. the link has been @e + visited). + */ + wxColour GetVisitedColour(); + + /** + Sets the colour used to print the label of the hyperlink when the mouse is over + the control. + */ + void SetHoverColour(const wxColour & colour); + + /** + Sets the colour used to print the label when the link has never been clicked + before + (i.e. the link has not been @e visited) and the mouse is not over the control. + */ + void SetNormalColour(const wxColour & colour); + + /** + Sets the URL associated with the hyperlink. + */ +#define void SetURL(const wxString & url) /* implementation is private */ + + /** + Marks the hyperlink as visited (see wxHyperlinkCtrl::SetVisitedColour). + */ + void SetVisited(bool visited = @true); + + /** + Sets the colour used to print the label when the mouse is not over the control + and the link has already been clicked before (i.e. the link has been @e + visited). + */ + void SetVisitedColour(const wxColour & colour); + + /** + Constructor. See Create() for more info. + */ + wxHyperLink(wxWindow* parent, wxWindowID id, + const wxString & label, + const wxString & url, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style, + const wxString& name = "hyperlink"); +}; diff --git a/interface/icon.h b/interface/icon.h new file mode 100644 index 0000000000..ff6a79e978 --- /dev/null +++ b/interface/icon.h @@ -0,0 +1,252 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: icon.h +// Purpose: documentation for wxIcon class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIcon + @wxheader{icon.h} + + An icon is a small rectangular bitmap usually used for denoting a + minimized application. It differs from a wxBitmap in always + having a mask associated with it for transparent drawing. On some platforms, + icons and bitmaps are implemented identically, since there is no real + distinction between + a wxBitmap with a mask and an icon; and there is no specific icon format on + some platforms (X-based applications usually standardize on XPMs for small + bitmaps + and icons). However, some platforms (such as Windows) make the distinction, so + a separate class is provided. + + @library{wxcore} + @category{gdi} + + @stdobjects + Objects: + wxNullIcon + + @seealso + @ref overview_wxbitmapoverview "Bitmap and icon overview", @ref + overview_supportedbitmapformats "supported bitmap file formats", wxDC::DrawIcon, wxCursor +*/ +class wxIcon : public wxBitmap +{ +public: + //@{ + /** + Loads an icon from the specified location. + + @param bits + Specifies an array of pixel values. + + @param width + Specifies the width of the icon. + + @param height + Specifies the height of the icon. + + @param desiredWidth + Specifies the desired width of the icon. This + parameter only has an effect in Windows (32-bit) where icon resources can + contain + several icons of different sizes. + + @param desiredWidth + Specifies the desired height of the icon. This + parameter only has an effect in Windows (32-bit) where icon resources can + contain + several icons of different sizes. + + @param depth + Specifies the depth of the icon. If this is omitted, the display depth of the + screen is used. + + @param name + This can refer to a resource name under MS Windows, or a filename under MS + Windows and X. + Its meaning is determined by the flags parameter. + + @param loc + The object describing the location of the native icon, see + wxIconLocation. + + @param type + May be one of the following: + + + wxBITMAP_TYPE_ICO + + + Load a Windows icon file. + + wxBITMAP_TYPE_ICO_RESOURCE + + + Load a Windows icon from the resource database. + + wxBITMAP_TYPE_GIF + + + Load a GIF bitmap file. + + wxBITMAP_TYPE_XBM + + + Load an X bitmap file. + + wxBITMAP_TYPE_XPM + + + Load an XPM bitmap file. + + The validity of these flags depends on the platform and wxWidgets configuration. + If all possible wxWidgets settings are used, the Windows platform supports ICO + file, ICO resource, + XPM data, and XPM file. Under wxGTK, the available formats are BMP file, XPM + data, XPM file, and PNG file. + Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file. + + @remarks The first form constructs an icon object with no data; an + assignment or another member function such as Create + or LoadFile must be called subsequently. + */ + wxIcon(); + wxIcon(const wxIcon& icon); + wxIcon(void* data, int type, int width, int height, + int depth = -1); + wxIcon(const char bits[], int width, int height, + int depth = 1); + wxIcon(int width, int height, int depth = -1); + wxIcon(const char* const* bits); + wxIcon(const wxString& name, wxBitmapType type, + int desiredWidth = -1, + int desiredHeight = -1); + wxIcon(const wxIconLocation& loc); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + + If the application omits to delete the icon explicitly, the icon will be + destroyed automatically by wxWidgets when the application exits. + + Do not delete an icon that is selected into a memory device context. + */ + ~wxIcon(); + + /** + Copies @e bmp bitmap to this icon. Under MS Windows the bitmap + must have mask colour set. + LoadFile() + + Wx::Icon-new( width, height, depth = -1 ) + Wx::Icon-new( name, type, desiredWidth = -1, desiredHeight = -1 ) + Wx::Icon-newFromBits( bits, width, height, depth = 1 ) + Wx::Icon-newFromXPM( data ) + */ + void CopyFromBitmap(const wxBitmap& bmp); + + /** + Gets the colour depth of the icon. A value of 1 indicates a + monochrome icon. + */ + int GetDepth(); + + /** + Gets the height of the icon in pixels. + */ + int GetHeight(); + + /** + Gets the width of the icon in pixels. + + @sa GetHeight() + */ + int GetWidth(); + + /** + Returns @true if icon data is present. + */ +#define bool IsOk() /* implementation is private */ + + /** + Loads an icon from a file or resource. + + @param name + Either a filename or a Windows resource name. + The meaning of name is determined by the type parameter. + + @param type + One of the following values: + + + wxBITMAP_TYPE_ICO + + + Load a Windows icon file. + + wxBITMAP_TYPE_ICO_RESOURCE + + + Load a Windows icon from the resource database. + + wxBITMAP_TYPE_GIF + + + Load a GIF bitmap file. + + wxBITMAP_TYPE_XBM + + + Load an X bitmap file. + + wxBITMAP_TYPE_XPM + + + Load an XPM bitmap file. + + The validity of these flags depends on the platform and wxWidgets configuration. + + @returns @true if the operation succeeded, @false otherwise. + + @sa wxIcon() + */ + bool LoadFile(const wxString& name, wxBitmapType type); + + /** + Sets the depth member (does not affect the icon data). + + @param depth + Icon depth. + */ + void SetDepth(int depth); + + /** + Sets the height member (does not affect the icon data). + + @param height + Icon height in pixels. + */ + void SetHeight(int height); + + /** + Sets the width member (does not affect the icon data). + + @param width + Icon width in pixels. + */ + void SetWidth(int width); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + + @param icon + Icon to assign. + */ + wxIcon operator =(const wxIcon& icon); +}; diff --git a/interface/iconbndl.h b/interface/iconbndl.h new file mode 100644 index 0000000000..031e4f79c4 --- /dev/null +++ b/interface/iconbndl.h @@ -0,0 +1,81 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: iconbndl.h +// Purpose: documentation for wxIconBundle class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIconBundle + @wxheader{iconbndl.h} + + This class contains multiple copies of an icon in different sizes, + see also wxDialog::SetIcons and + wxTopLevelWindow::SetIcons. + + @library{wxcore} + @category{FIXME} + + @stdobjects + wxNullIconBundle +*/ +class wxIconBundle : public wxGDIObject +{ +public: + //@{ + /** + Copy constructor. + */ + wxIconBundle(); + wxIconBundle(const wxString& file, long type); + wxIconBundle(const wxIcon& icon); + wxIconBundle(const wxIconBundle& ic); + //@} + + /** + Destructor. + */ + ~wxIconBundle(); + + //@{ + /** + Adds the icon to the collection; if the collection already + contains an icon with the same width and height, it is + replaced by the new one. + */ + void AddIcon(const wxString& file, long type); + void AddIcon(const wxIcon& icon); + //@} + + //@{ + /** + Same as GetIcon( wxSize( size, size ) ). + */ + wxIcon GetIcon(const wxSize& size); + wxIcon GetIcon(wxCoord size = -1); + //@} + + /** + Returns the icon with exactly the given size or @c wxNullIcon if this + size is not available. + */ + wxIcon GetIconOfExactSize(const wxSize& size); + + /** + Returns @true if the bundle doesn't contain any icons, @false otherwise (in + which case a call to GetIcon() with default + parameter should return a valid icon). + */ + bool IsEmpty(); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxIconBundle operator =(const wxIconBundle& ic); + + /** + Equality operator. This returns @true if two icon bundles are equal. + */ + bool operator ==(const wxIconBundle& ic); +}; diff --git a/interface/iconloc.h b/interface/iconloc.h new file mode 100644 index 0000000000..fa8037aaff --- /dev/null +++ b/interface/iconloc.h @@ -0,0 +1,39 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: iconloc.h +// Purpose: documentation for wxIconLocation class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIconLocation + @wxheader{iconloc.h} + + wxIconLocation is a tiny class describing the location of an (external, i.e. + not embedded into the application resources) icon. For most platforms it simply + contains the file name but under some others (notably Windows) the same file + may contain multiple icons and so this class also stores the index of the icon + inside the file. + + In any case, its details should be of no interest to the application code and + most of them are not even documented here (on purpose) as it is only meant to + be used as an opaque class: the application may get the object of this class + from somewhere and the only reasonable thing to do with it later is to create + a wxIcon from it. + + @library{wxbase} + @category{FIXME} + + @seealso + wxIcon, wxFileType::GetIcon +*/ +class wxIconLocation +{ +public: + /** + Returns @true if the object is valid, i.e. was properly initialized, and + @false otherwise. + */ +#define bool IsOk() /* implementation is private */ +}; diff --git a/interface/image.h b/interface/image.h new file mode 100644 index 0000000000..ecf56c1432 --- /dev/null +++ b/interface/image.h @@ -0,0 +1,1228 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: image.h +// Purpose: documentation for wxImageHandler class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxImageHandler + @wxheader{image.h} + + This is the base class for implementing image file loading/saving, and image + creation from data. + It is used within wxImage and is not normally seen by the application. + + If you wish to extend the capabilities of wxImage, derive a class from + wxImageHandler + and add the handler using wxImage::AddHandler in your + application initialisation. + + @library{wxcore} + @category{FIXME} + + @seealso + wxImage, wxInitAllImageHandlers +*/ +class wxImageHandler : public wxObject +{ +public: + /** + Default constructor. In your own default constructor, initialise the members + m_name, m_extension and m_type. + */ + wxImageHandler(); + + /** + Destroys the wxImageHandler object. + */ + ~wxImageHandler(); + + /** + Gets the file extension associated with this handler. + */ + const wxString GetExtension(); + + /** + If the image file contains more than one image and the image handler is capable + of retrieving these individually, this function will return the number of + available images. + + @param stream + Opened input stream for reading image data. Currently, the stream must support + seeking. + + @returns Number of available images. For most image handlers, this is 1 + (exceptions are TIFF and ICO formats). + */ + int GetImageCount(wxInputStream& stream); + + /** + Gets the MIME type associated with this handler. + */ + const wxString GetMimeType(); + + /** + Gets the name of this handler. + */ + const wxString GetName(); + + /** + Gets the image type associated with this handler. + */ + long GetType(); + + /** + Loads a image from a stream, putting the resulting data into @e image. If the + image file contains + more than one image and the image handler is capable of retrieving these + individually, @e index + indicates which image to read from the stream. + + @param image + The image object which is to be affected by this operation. + + @param stream + Opened input stream for reading image data. + + @param verbose + If set to @true, errors reported by the image handler will produce wxLogMessages. + + @param index + The index of the image in the file (starting from zero). + + @returns @true if the operation succeeded, @false otherwise. + + @sa wxImage::LoadFile, wxImage::SaveFile, SaveFile() + */ + bool LoadFile(wxImage* image, wxInputStream& stream, + bool verbose=@true, int index=0); + + /** + Saves a image in the output stream. + + @param image + The image object which is to be affected by this operation. + + @param stream + Opened output stream for writing the data. + + @returns @true if the operation succeeded, @false otherwise. + + @sa wxImage::LoadFile, wxImage::SaveFile, LoadFile() + */ + bool SaveFile(wxImage* image, wxOutputStream& stream); + + /** + Sets the handler extension. + + @param extension + Handler extension. + */ + void SetExtension(const wxString& extension); + + /** + Sets the handler MIME type. + + @param mimename + Handler MIME type. + */ + void SetMimeType(const wxString& mimetype); + + /** + Sets the handler name. + + @param name + Handler name. + */ + void SetName(const wxString& name); +}; + + +/** + @class wxImage + @wxheader{image.h} + + This class encapsulates a platform-independent image. An image can be created + from data, or using wxBitmap::ConvertToImage. An image + can be loaded from a file in a variety of formats, and is extensible to new + formats + via image format handlers. Functions are available to set and get image bits, so + it can be used for basic image manipulation. + + A wxImage cannot (currently) be drawn directly to a wxDC. Instead, + a platform-specific wxBitmap object must be created from it using + the wxBitmap::wxBitmap(wxImage,int depth) constructor. + This bitmap can then + be drawn in a device context, using wxDC::DrawBitmap. + + One colour value of the image may be used as a mask colour which will lead to + the automatic + creation of a wxMask object associated to the bitmap object. + + @library{wxcore} + @category{gdi} + + @seealso + wxBitmap, wxInitAllImageHandlers +*/ +class wxImage : public wxObject +{ +public: + //@{ + /** + Creates an image from XPM data. + + @param width + Specifies the width of the image. + + @param height + Specifies the height of the image. + + @param name + Name of the file from which to load the image. + + @param stream + Opened input stream from which to load the image. Currently, the stream must + support seeking. + + @param type + May be one of the following: + + wxBITMAP_TYPE_BMP + + + Load a Windows bitmap file. + + wxBITMAP_TYPE_GIF + + + Load a GIF bitmap file. + + wxBITMAP_TYPE_JPEG + + + Load a JPEG bitmap file. + + wxBITMAP_TYPE_PNG + + + Load a PNG bitmap file. + + wxBITMAP_TYPE_PCX + + + Load a PCX bitmap file. + + wxBITMAP_TYPE_PNM + + + Load a PNM bitmap file. + + wxBITMAP_TYPE_TIF + + + Load a TIFF bitmap file. + + wxBITMAP_TYPE_TGA + + + Load a TGA bitmap file. + + wxBITMAP_TYPE_XPM + + + Load a XPM bitmap file. + + wxBITMAP_TYPE_ICO + + + Load a Windows icon file (ICO). + + wxBITMAP_TYPE_CUR + + + Load a Windows cursor file (CUR). + + wxBITMAP_TYPE_ANI + + + Load a Windows animated cursor file (ANI). + + wxBITMAP_TYPE_ANY + + + Will try to autodetect the format. + + @param mimetype + MIME type string (for example 'image/jpeg') + + @param index + Index of the image to load in the case that the image file contains multiple + images. + This is only used by GIF, ICO and TIFF handlers. The default value (-1) means + "choose the default image" and is interpreted as the first image (index=0) by + the GIF and TIFF handler and as the largest and most colourful one by the ICO + handler. + + @param xpmData + A pointer to XPM image data. + + @remarks Depending on how wxWidgets has been configured, not all formats + may be available. + + @sa LoadFile() + */ + wxImage(); + wxImage(const wxImage& image); + wxImage(const wxBitmap& bitmap); + wxImage(int width, int height, bool clear=@true); + wxImage(int width, int height, unsigned char* data, + bool static_data = @false); + wxImage(const wxString& name, long type = wxBITMAP_TYPE_ANY, + int index = -1); + wxImage(const wxString& name, const wxString& mimetype, + int index = -1); + wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, + int index = -1); + wxImage(wxInputStream& stream, const wxString& mimetype, + int index = -1); + wxImage(const char* const* xpmData); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxImage(); + + //@{ + /** + returns @true if the current image handlers can read this file + */ + static void AddHandler(wxImageHandler* handler); + See also bool CanRead(const wxString& filename); + //@} + + /** + Blurs the image in both horizontal and vertical directions by the specified + pixel + @e blurRadius. This should not be used when using a single mask colour + for transparency. + + @sa @ref horzblur() BlurHorizontal, @ref vertblur() BlurVertical + */ + wxImage Blur(int blurRadius); + + /** + Blurs the image in the horizontal direction only. This should not be used + when using a single mask colour for transparency. + + @sa Blur(), @ref vertblur() BlurVertical + */ + wxImage BlurHorizontal(int blurRadius); + + /** + Blurs the image in the vertical direction only. This should not be used + when using a single mask colour for transparency. + + @sa Blur(), @ref horzblur() BlurHorizontal + */ + wxImage BlurVertical(int blurRadius); + + /** + Deletes all image handlers. + + This function is called by wxWidgets on exit. + */ + static void CleanUpHandlers(); + + /** + Computes the histogram of the image. @e histogram is a reference to + wxImageHistogram object. wxImageHistogram is a specialization of + wxHashMap "template" and is defined as follows: + + @returns Returns number of colours in the histogram. + */ + unsigned long ComputeHistogram(wxImageHistogram& histogram); + + /** + If the image has alpha channel, this method converts it to mask. All pixels + with alpha value less than @e 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. + + @returns @false if FindFirstUnusedColour returns @false, @true otherwise. + */ + bool ConvertAlphaToMask(unsigned char threshold = 128); + + /** + Deprecated, use equivalent @ref wxBitmap::ctor "wxBitmap constructor" + (which takes wxImage and depth as its arguments) instead. + */ + wxBitmap ConvertToBitmap(); + + /** + Returns a greyscale version of the image. The returned image uses the luminance + component of the original to calculate the greyscale. Defaults to using + ITU-T BT.601 when converting to YUV, where every pixel equals + (R * @e lr) + (G * @e lg) + (B * @e lb). + */ + wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, + double lb = 0.114); + + /** + Returns monochromatic version of the image. The returned image has white + colour where the original has @e (r,g,b) colour and black colour + everywhere else. + */ + wxImage ConvertToMono(unsigned char r, unsigned char g, + unsigned char b); + + /** + Returns an identical copy of the image. + */ + wxImage Copy(); + + /** + Creates a fresh image. If @e clear is @true, the new image will be initialized + to black. + Otherwise, the image data will be uninitialized. + + @param width + The width of the image in pixels. + + @param height + The height of the image in pixels. + + @returns @true if the call succeeded, @false otherwise. + */ + bool Create(int width, int height, bool clear=@true); + + /** + Destroys the image data. + */ + void Destroy(); + + /** + @param r,g,b + Pointers to variables to save the colour. + + @param startR,startG,startB + Initial values of the colour. Returned colour + will have RGB values equal to or greater than these. + + @returns Returns @false if there is no unused colour left, @true on success. + */ + bool FindFirstUnusedColour(unsigned char * r, unsigned char * g, + unsigned char * b, + unsigned char startR = 1, + unsigned char startG = 0, + unsigned char startB = 0); + + //@{ + /** + Finds the handler associated with the given MIME type. + + @param name + The handler name. + + @param extension + The file extension, such as "bmp". + + @param imageType + The image type, such as wxBITMAP_TYPE_BMP. + + @param mimetype + MIME type. + + @returns A pointer to the handler if found, @NULL otherwise. + + @sa wxImageHandler + */ + static wxImageHandler* FindHandler(const wxString& name); + static wxImageHandler* FindHandler(const wxString& extension, + long imageType); + static wxImageHandler* FindHandler(long imageType); + static wxImageHandler* FindHandlerMime(const wxString& mimetype); + //@} + + //@{ + /** + 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 @ref getdata() RGB ones. + */ + unsigned char GetAlpha(int x, int y); + unsigned char * GetAlpha(); + //@} + + /** + Returns the blue intensity at the given coordinate. + */ + unsigned char GetBlue(int x, int y); + + /** + Returns the image data as an array. This is most often used when doing + direct image manipulation. The return value points to an array of + characters in RGBRGBRGB... format in the top-to-bottom, left-to-right + order, that is the first RGB triplet corresponds to the pixel first pixel of + the first row, the second one --- to the second pixel of the first row and so + on until the end of the first row, with second row following after it and so + on. + + You should not delete the returned pointer nor pass it to + SetData(). + */ + unsigned char* GetData(); + + /** + Returns the green intensity at the given coordinate. + */ + unsigned char GetGreen(int x, int y); + + /** + Returns the static list of image format handlers. + + @sa wxImageHandler + */ + static wxList GetHandlers(); + + /** + Gets the height of the image in pixels. + */ + int GetHeight(); + + //@{ + /** + If the image file contains more than one image and the image handler is capable + of retrieving these individually, this function will return the number of + available images. + + @param name + Name of the file to query. + + @param stream + Opened input stream with image data. Currently, the stream must support seeking. + + @param type + May be one of the following: + + wxBITMAP_TYPE_BMP + + + Load a Windows bitmap file. + + wxBITMAP_TYPE_GIF + + + Load a GIF bitmap file. + + wxBITMAP_TYPE_JPEG + + + Load a JPEG bitmap file. + + wxBITMAP_TYPE_PNG + + + Load a PNG bitmap file. + + wxBITMAP_TYPE_PCX + + + Load a PCX bitmap file. + + wxBITMAP_TYPE_PNM + + + Load a PNM bitmap file. + + wxBITMAP_TYPE_TIF + + + Load a TIFF bitmap file. + + wxBITMAP_TYPE_XPM + + + Load a XPM bitmap file. + + wxBITMAP_TYPE_ICO + + + Load a Windows icon file (ICO). + + wxBITMAP_TYPE_CUR + + + Load a Windows cursor file (CUR). + + wxBITMAP_TYPE_ANI + + + Load a Windows animated cursor file (ANI). + + wxBITMAP_TYPE_ANY + + + Will try to autodetect the format. + + @returns Number of available images. For most image handlers, this is 1 + (exceptions are TIFF and ICO formats). + */ + static int GetImageCount(const wxString& filename, + long type = wxBITMAP_TYPE_ANY); + static int GetImageCount(wxInputStream& stream, + long type = wxBITMAP_TYPE_ANY); + //@} + + /** + Iterates all registered wxImageHandler objects, and returns a string containing + file extension masks + suitable for passing to file open/save dialog boxes. + + @returns The format of the returned string is + "(*.ext1;*.ext2)|*.ext1;*.ext2". + + @sa wxImageHandler + */ + static wxString GetImageExtWildcard(); + + /** + Gets the blue value of the mask colour. + */ + unsigned char GetMaskBlue(); + + /** + Gets the green value of the mask colour. + */ + unsigned char GetMaskGreen(); + + /** + Gets the red value of the mask colour. + */ + unsigned char GetMaskRed(); + + /** + Gets a user-defined option. The function is case-insensitive to @e name. + + For example, when saving as a JPEG file, the option @b quality is + used, which is a number between 0 and 100 (0 is terrible, 100 is very good). + + @sa SetOption(), GetOptionInt(), HasOption() + */ + wxString GetOption(const wxString& name); + + /** + Gets a user-defined option as an integer. The function is case-insensitive to + @e name. + + If the given option is not present, the function returns 0. Use + HasOption() is 0 is a possibly valid value + for the option. + + Options for wxPNGHandler + + + 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. + + + @sa SetOption(), GetOption() + */ + int GetOptionInt(const wxString& name); + + /** + Get the current mask colour or find a suitable unused colour that could be + used as a mask colour. Returns @true if the image currently has a mask. + */ + bool GetOrFindMaskColour(unsigned char r, unsigned char g, + unsigned char b); + + /** + Returns the palette associated with the image. Currently the palette is only + used when converting to wxBitmap under Windows. Some of the wxImage handlers + have been modified to set the palette if one exists in the image file (usually + 256 or less colour images in GIF or PNG format). + */ + const wxPalette GetPalette(); + + /** + Returns the red intensity at the given coordinate. + */ + unsigned char GetRed(int x, int y); + + /** + Returns a sub image of the current one as long as the rect belongs entirely to + the image. + */ + wxImage GetSubImage(const wxRect& rect); + + /** + Gets the width of the image in pixels. + + @sa GetHeight() + */ + int GetWidth(); + + /** + Constructor for HSVValue, an object that contains values for hue, saturation + and value which + represent the value of a color. It is used by HSVtoRGB() + and RGBtoHSV(), which + converts between HSV color space and RGB color space. + */ + HSVValue(double h = 0.0, double s = 0.0, double v = 0.0); + + /** + Converts a color in HSV color space to RGB color space. + */ +#define wxImage::RGBValue HSVtoRGB(const HSVValue & hsv) /* implementation is private */ + + /** + Returns @true if this image has alpha channel, @false otherwise. + + @sa GetAlpha(), SetAlpha() + */ + bool HasAlpha(); + + /** + Returns @true if there is a mask active, @false otherwise. + */ + bool HasMask(); + + /** + Returns @true if the given option is present. The function is case-insensitive + to @e name. + + @sa SetOption(), GetOption(), GetOptionInt() + */ + bool HasOption(const wxString& 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. + */ + void InitAlpha(); + + /** + Internal use only. Adds standard image format handlers. It only install BMP + for the time being, which is used by wxBitmap. + + This function is called by wxWidgets on startup, and shouldn't be called by + the user. + + @sa wxImageHandler, wxInitAllImageHandlers, wxQuantize + */ + static void InitStandardHandlers(); + + /** + Adds a handler at the start of the static list of format handlers. + + @param handler + A new image format handler object. There is usually only one instance + of a given handler class in an application session. + + @sa wxImageHandler + */ + static void InsertHandler(wxImageHandler* handler); + + /** + Returns @true if image data is present. + */ +#define bool IsOk() /* implementation is private */ + + /** + Returns @true if the given pixel is transparent, i.e. either has the mask + colour if this image has a mask or if this image has alpha channel and alpha + value of this pixel is strictly less than @e threshold. + */ + bool IsTransparent(int x, int y, unsigned char threshold = 128); + + //@{ + /** + Loads an image from an input stream. + + @param name + Name of the file from which to load the image. + + @param stream + Opened input stream from which to load the image. Currently, the stream must + support seeking. + + @param type + One of the following values: + + wxBITMAP_TYPE_BMP + + + Load a Windows image file. + + wxBITMAP_TYPE_GIF + + + Load a GIF image file. + + wxBITMAP_TYPE_JPEG + + + Load a JPEG image file. + + wxBITMAP_TYPE_PCX + + + Load a PCX image file. + + wxBITMAP_TYPE_PNG + + + Load a PNG image file. + + wxBITMAP_TYPE_PNM + + + Load a PNM image file. + + wxBITMAP_TYPE_TIF + + + Load a TIFF image file. + + wxBITMAP_TYPE_XPM + + + Load a XPM image file. + + wxBITMAP_TYPE_ICO + + + Load a Windows icon file (ICO). + + wxBITMAP_TYPE_CUR + + + Load a Windows cursor file (CUR). + + wxBITMAP_TYPE_ANI + + + Load a Windows animated cursor file (ANI). + + wxBITMAP_TYPE_ANY + + + Will try to autodetect the format. + + @param mimetype + MIME type string (for example 'image/jpeg') + + @param index + Index of the image to load in the case that the image file contains multiple + images. + This is only used by GIF, ICO and TIFF handlers. The default value (-1) means + "choose the default image" and is interpreted as the first image (index=0) by + the GIF and TIFF handler and as the largest and most colourful one by the ICO + handler. + + @returns @true if the operation succeeded, @false otherwise. If the + optional index parameter is out of range, @false is + returned and a call to wxLogError() takes place. + + @remarks Depending on how wxWidgets has been configured, not all formats + may be available. + + @sa SaveFile() + */ + bool LoadFile(const wxString& name, + long type = wxBITMAP_TYPE_ANY, + int index = -1); + bool LoadFile(const wxString& name, const wxString& mimetype, + int index = -1); + bool LoadFile(wxInputStream& stream, long type, + int index = -1); + bool LoadFile(wxInputStream& stream, + const wxString& mimetype, + int index = -1); + //@} + + /** + Returns a mirrored copy of the image. The parameter @e horizontally + indicates the orientation. + */ + wxImage Mirror(bool horizontally = @true); + + /** + Copy the data of the given @e image to the specified position in this image. + */ + void Paste(const wxImage& image, int x, int y); + + /** + Constructor for RGBValue, an object that contains values for red, green and + blue which + represent the value of a color. It is used by HSVtoRGB() + and RGBtoHSV(), which + converts between HSV color space and RGB color space. + */ + RGBValue(unsigned char r = 0, unsigned char g = 0, + unsigned char b = 0); + + /** + Converts a color in RGB color space to HSV color space. + */ +#define wxImage::HSVValue RGBtoHSV(const RGBValue& rgb) /* implementation is private */ + + /** + Finds the handler with the given name, and removes it. The handler + is not deleted. + + @param name + The handler name. + + @returns @true if the handler was found and removed, @false otherwise. + + @sa wxImageHandler + */ + static bool RemoveHandler(const wxString& name); + + /** + Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2. + */ + void Replace(unsigned char r1, unsigned char g1, + unsigned char b1, unsigned char r2, + unsigned char g2, unsigned char b2); + + /** + Changes the size of the image in-place by scaling it: after a call to this + function, + the image will have the given width and height. + + For a description of the @e quality parameter, see the Scale() function. + + Returns the (modified) image itself. + + @sa Scale() + */ + wxImage Rescale(int width, int height, + int quality = wxIMAGE_QUALITY_NORMAL); + + /** + Changes the size of the image in-place without scaling it by adding either a + border + with the given colour or cropping as necessary. The image is pasted into a new + image with the given @e size and background colour at the position @e pos + relative to the upper left of the new image. If @e 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. + + @sa Size() + */ + wxImage Resize(const wxSize& size, const wxPoint pos, + int red = -1, int green = -1, + int blue = -1); + + /** + Rotates the image about the given point, by @e angle radians. Passing @true + to @e interpolating results in better image quality, but is slower. If the + image has a mask, then the mask colour is used for the uncovered pixels in the + rotated image background. Else, black (rgb 0, 0, 0) will be used. + + Returns the rotated image, leaving this image intact. + */ + wxImage Rotate(double angle, const wxPoint& rotationCentre, + bool interpolating = @true, + wxPoint* offsetAfterRotation = @NULL); + + /** + Returns a copy of the image rotated 90 degrees in the direction + indicated by @e clockwise. + */ + wxImage Rotate90(bool clockwise = @true); + + /** + Rotates the hue of each pixel in the image by @e angle, which is a double in + the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0 + corresponds + to +360 degrees. + */ + void RotateHue(double angle); + + //@{ + /** + Saves an image in the given stream. + + @param name + Name of the file to save the image to. + + @param stream + Opened output stream to save the image to. + + @param type + Currently these types can be used: + + wxBITMAP_TYPE_BMP + + + Save a BMP image file. + + wxBITMAP_TYPE_JPEG + + + Save a JPEG image file. + + wxBITMAP_TYPE_PNG + + + Save a PNG image file. + + wxBITMAP_TYPE_PCX + + + Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit + otherwise). + + wxBITMAP_TYPE_PNM + + + Save a PNM image file (as raw RGB always). + + wxBITMAP_TYPE_TIFF + + + Save a TIFF image file. + + wxBITMAP_TYPE_XPM + + + Save a XPM image file. + + wxBITMAP_TYPE_ICO + + + Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high. A + single image is saved in 8 colors at the size supplied). + + wxBITMAP_TYPE_CUR + + + Save a Windows cursor file (CUR). + + @param mimetype + MIME type. + + @returns @true if the operation succeeded, @false otherwise. + + @remarks Depending on how wxWidgets has been configured, not all formats + may be available. + + @sa LoadFile() + */ + bool SaveFile(const wxString& name, int type); + bool SaveFile(const wxString& name, const wxString& mimetype); + bool SaveFile(const wxString& name); + bool SaveFile(wxOutputStream& stream, int type); + bool SaveFile(wxOutputStream& stream, + const wxString& mimetype); + //@} + + /** + Returns a scaled version of the image. This is also useful for + scaling bitmaps in general as the only other way to scale bitmaps + is to blit a wxMemoryDC into another wxMemoryDC. + + It should be noted that although using wxIMAGE_QUALITY_HIGH produces much nicer + looking results it is a slower method. Downsampling will use the box averaging + method + which seems to operate very fast. If you are upsampling larger images using + this method you will most likely notice that it is a bit slower and in extreme + cases + it will be quite substantially slower as the bicubic algorithm has to process a + lot of + data. + + It should also be noted that the high quality scaling may not work as expected + when using a single mask colour for transparency, as the scaling will blur the + image and will therefore remove the mask partially. Using the alpha channel + will work. + + Example: + + @param quality + Determines what method to use for resampling the image. Can be one of the + following: + + wxIMAGE_QUALITY_NORMAL + + + Uses the normal default scaling method of pixel replication + + wxIMAGE_QUALITY_HIGH + + + Uses bicubic and box averaging resampling methods for upsampling and + downsampling respectively + + @sa Rescale() + */ + wxImage Scale(int width, int height, + int quality = wxIMAGE_QUALITY_NORMAL); + + //@{ + /** + Sets the alpha value for the given pixel. This function should only be called + if the image has alpha channel data, use HasAlpha() to + check for this. + */ + void SetAlpha(unsigned char * alpha = @NULL, + bool static_data = @false); + void SetAlpha(int x, int y, unsigned char alpha); + //@} + + /** + Sets the image data without performing checks. The data given must have + the size (width*height*3) or results will be unexpected. Don't use this + method if you aren't sure you know what you are doing. + + The data must have been allocated with @c malloc(), @b NOT with + @c operator new. + + After this call the pointer to the data is owned by the wxImage object, + that will be responsible for deleting it. + Do not pass to this function a pointer obtained through + GetData(). + */ + void SetData(unsigned char* data); + + /** + Specifies whether there is a mask or not. The area of the mask is determined by + the current mask colour. + */ + void SetMask(bool hasMask = @true); + + /** + Sets the mask colour for this image (and tells the image to use the mask). + */ + void SetMaskColour(unsigned char red, unsigned char green, + unsigned char blue); + + /** + @param mask + The mask image to extract mask shape from. Must have same dimensions as the + image. + + @param mr,mg,mb + RGB value of pixels in mask that will be used to create the mask. + + @returns Returns @false if mask does not have same dimensions as the image + or if there is no unused colour left. Returns @true if + the mask was successfully applied. + */ + bool SetMaskFromImage(const wxImage& mask, unsigned char mr, + unsigned char mg, + unsigned char mb); + + //@{ + /** + Sets a user-defined option. The function is case-insensitive to @e name. + + For example, when saving as a JPEG file, the option @b quality is + used, which is a number between 0 and 100 (0 is terrible, 100 is very good). + + @sa GetOption(), GetOptionInt(), HasOption() + */ + void SetOption(const wxString& name, const wxString& value); + void SetOption(const wxString& name, int value); + //@} + + /** + Associates a palette with the image. The palette may be used when converting + wxImage to wxBitmap (MSW only at present) or in file save operations (none as + yet). + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the colour of the pixels within the given rectangle. This routine performs + bounds-checks for the coordinate so it can be considered a safe way to + manipulate the + data. + */ +#define void SetRGB(wxRect & rect, unsigned char red, + unsigned char green, + unsigned char blue) /* implementation is private */ + + /** + 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 @e size and background colour at the position @e pos + relative to the upper left of the new image. If @e red = green = blue = -1 + then the areas of the larger image not covered by this image are made + transparent by filling them with the image mask colour (which will be allocated + automatically if it isn't currently set). Otherwise, the areas will be filled + with the colour with the specified RGB components. + + @sa Resize() + */ + wxImage Size(const wxSize& size, const wxPoint pos, int red = -1, + int green = -1, int blue = -1); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + + @param image + Image to assign. + + @returns Returns 'this' object. + */ + wxImage operator =(const wxImage& image); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Initializes all available image handlers. For a list of available handlers, + see wxImage. + + @sa wxImage, wxImageHandler +*/ +void wxInitAllImageHandlers(); + diff --git a/interface/imaglist.h b/interface/imaglist.h new file mode 100644 index 0000000000..8551a458e5 --- /dev/null +++ b/interface/imaglist.h @@ -0,0 +1,198 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: imaglist.h +// Purpose: documentation for wxImageList class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxImageList + @wxheader{imaglist.h} + + A wxImageList contains a list of images, which are stored in + an unspecified form. Images can have masks for transparent + drawing, and can be made from a variety of sources including bitmaps + and icons. + + wxImageList is used principally in conjunction with wxTreeCtrl and + wxListCtrl classes. + + @library{wxcore} + @category{gdi} + + @seealso + wxTreeCtrl, wxListCtrl +*/ +class wxImageList : public wxObject +{ +public: + //@{ + /** + Constructor specifying the image size, whether image masks should be created, + and the initial size of the list. + + @param width + Width of the images in the list. + + @param height + Height of the images in the list. + + @param mask + @true if masks should be created for all images. + + @param initialCount + The initial size of the list. + + @sa Create() + */ + wxImageList(); + wxImageList(int width, int height, bool mask = @true, + int initialCount = 1); + //@} + + //@{ + /** + Adds a new image using an icon. + + @param bitmap + Bitmap representing the opaque areas of the image. + + @param mask + Monochrome mask bitmap, representing the transparent areas of the image. + + @param maskColour + Colour indicating which parts of the image are transparent. + + @param icon + Icon to use as the image. + + @returns The new zero-based image index. + + @remarks The original bitmap or icon is not affected by the Add + operation, and can be deleted afterwards. + */ + int Add(const wxBitmap& bitmap, + const wxBitmap& mask = wxNullBitmap); + int Add(const wxBitmap& bitmap, const wxColour& maskColour); + int Add(const wxIcon& icon); + //@} + + /** + Initializes the list. See wxImageList() for details. + */ + bool Create(int width, int height, bool mask = @true, + int initialCount = 1); + + /** + Draws a specified image onto a device context. + + @param index + Image index, starting from zero. + + @param dc + Device context to draw on. + + @param x + X position on the device context. + + @param y + Y position on the device context. + + @param flags + How to draw the image. A bitlist of a selection of the following: + + wxIMAGELIST_DRAW_NORMAL + + + Draw the image normally. + + wxIMAGELIST_DRAW_TRANSPARENT + + + Draw the image with transparency. + + wxIMAGELIST_DRAW_SELECTED + + + Draw the image in selected state. + + wxIMAGELIST_DRAW_FOCUSED + + + Draw the image in a focused state. + + @param solidBackground + For optimisation - drawing can be faster if the function is told + that the background is solid. + */ + bool Draw(int index, wxDC& dc, int x, int y, + int flags = wxIMAGELIST_DRAW_NORMAL, + bool solidBackground = @false); + + /** + Returns the bitmap corresponding to the given index. + */ + wxBitmap GetBitmap(int index); + + /** + Returns the icon corresponding to the given index. + */ + wxIcon GetIcon(int index); + + /** + Returns the number of images in the list. + */ + int GetImageCount(); + + /** + Retrieves the size of the images in the list. Currently, the @e index + parameter is ignored as all images in the list have the same size. + + @param index + currently unused, should be 0 + + @param width + receives the width of the images in the list + + @param height + receives the height of the images in the list + + @returns @true if the function succeeded, @false if it failed (for example, + if the image list was not yet initialized). + */ + bool GetSize(int index, int& width, int & height); + + /** + Removes the image at the given position. + */ + bool Remove(int index); + + /** + Removes all the images in the list. + */ + bool RemoveAll(); + + //@{ + /** + Replaces the existing image with the new image. + + @param bitmap + Bitmap representing the opaque areas of the image. + + @param mask + Monochrome mask bitmap, representing the transparent areas of the image. + + @param icon + Icon to use as the image. + + @returns @true if the replacement was successful, @false otherwise. + + @remarks The original bitmap or icon is not affected by the Replace + operation, and can be deleted afterwards. + */ + bool Replace(int index, const wxBitmap& bitmap, + const wxBitmap& mask = wxNullBitmap); + bool Replace(int index, const wxIcon& icon); + //@} +}; diff --git a/interface/init.h b/interface/init.h new file mode 100644 index 0000000000..b0d150d2bf --- /dev/null +++ b/interface/init.h @@ -0,0 +1,27 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: init.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + Free resources allocated by a successful call to wxEntryStart. +*/ +void wxEntryCleanup(); + + + //@{ +/** + (notice that under Windows CE platform, and only there, the type of + @e pCmdLine is @c wchar_t *, otherwise it is @c char *, even in + Unicode build). +*/ +bool wxEntryStart(int& argc, wxChar ** argv); + bool wxEntryStart(HINSTANCE hInstance, + HINSTANCE hPrevInstance = @NULL, + char * pCmdLine = @NULL, + int nCmdShow = SW_SHOWNORMAL); +//@} + diff --git a/interface/intl.h b/interface/intl.h new file mode 100644 index 0000000000..172335b070 --- /dev/null +++ b/interface/intl.h @@ -0,0 +1,661 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: intl.h +// Purpose: documentation for wxLocale class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxLocale + @wxheader{intl.h} + + wxLocale class encapsulates all language-dependent settings and is a + generalization of the C locale concept. + + In wxWidgets this class manages message catalogs which contain the translations + of the strings used to the current language. + + @b wxPerl note: In wxPerl you can't use the '_' function name, so + the @c Wx::Locale module can export the @c gettext and + @c gettext_noop under any given name. + + @code + # this imports gettext ( equivalent to Wx::GetTranslation + # and gettext_noop ( a noop ) + # into your module + use Wx::Locale qw(:default); + + # .... + + # use the functions + print gettext( ``Panic!'' ); + + button = Wx::Button-new( window, -1, gettext( ``Label'' ) ); + @endcode + + If you need to translate a lot of strings, then adding gettext( ) around + each one is a long task ( that is why _( ) was introduced ), so just choose + a shorter name for gettext: + + @code + # + use Wx::Locale 'gettext' = 't', + 'gettext_noop' = 'gettext_noop'; + + # ... + + # use the functions + print t( ``Panic!!'' ); + + # ... + @endcode + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_internationalization "Internationalization overview", @ref + overview_sampleinternat "Internat sample", wxXLocale +*/ +class wxLocale +{ +public: + //@{ + /** + See Init() for parameters description. + + The call of this function has several global side effects which you should + understand: first of all, the application locale is changed - note that this + will affect many of standard C library functions such as printf() or strftime(). + Second, this wxLocale object becomes the new current global locale for the + application and so all subsequent calls to wxGetTranslation() will try to + translate the messages using the message catalogs for this locale. + */ + wxLocale(); + wxLocale(int language, + int flags = + wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); + wxLocale(const wxString& name, + const wxString& short = wxEmptyString, + const wxString& locale = wxEmptyString, + bool bLoadDefault = @true, + bool bConvertEncoding = @false); + //@} + + /** + The destructor, like the constructor, also has global side effects: the + previously + set locale is restored and so the changes described in + Init() documentation are rolled back. + */ + ~wxLocale(); + + //@{ + /** + Add a catalog for use with the current locale: it is searched for in standard + places (current directory first, then the system one), but you may also prepend + additional directories to the search path with + AddCatalogLookupPathPrefix(). + + All loaded catalogs will be used for message lookup by + GetString() for the current locale. + + Returns @true if catalog was successfully loaded, @false otherwise (which might + mean that the catalog is not found or that it isn't in the correct format). + + The second form of this method takes two additional arguments, + @e msgIdLanguage and @e msgIdCharset. + + @e msgIdLanguage specifies the language of "msgid" strings in source code + (i.e. arguments to GetString(), + wxGetTranslation and the + _ macro). It is used if AddCatalog cannot find any + catalog for current language: if the language is same as source code language, + then strings from source code are used instead. + + @e msgIdCharset lets you specify the charset used for msgids in sources + in case they use 8-bit characters (e.g. German or French strings). This + argument has no effect in Unicode build, because literals in sources are + Unicode strings; you have to use compiler-specific method of setting the right + charset when compiling with Unicode. + + By default (i.e. when you use the first form), msgid strings are assumed + to be in English and written only using 7-bit ASCII characters. + + If you have to deal with non-English strings or 8-bit characters in the source + code, see the instructions in + @ref overview_nonenglishoverview "Writing non-English applications". + */ + bool AddCatalog(const wxString& domain); + bool AddCatalog(const wxString& domain, + wxLanguage msgIdLanguage, + const wxString& msgIdCharset); + //@} + + /** + Add a prefix to the catalog lookup path: the message catalog files will be + looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix + (in this order). + + This only applies to subsequent invocations of AddCatalog(). + */ + void AddCatalogLookupPathPrefix(const wxString& prefix); + + /** + Adds custom, user-defined language to the database of known languages. This + database is used in conjunction with the first form of + Init(). + + wxLanguageInfo is defined as follows: + + @e Language should be greater than wxLANGUAGE_USER_DEFINED. + + Wx::LanguageInfo-new( language, canonicalName, WinLang, WinSubLang, Description + ) + */ + static void AddLanguage(const wxLanguageInfo& info); + + /** + This function may be used to find the language description structure for the + given locale, specified either as a two letter ISO language code (for example, + "pt"), a language code followed by the country code ("pt_BR") or a full, human + readable, language description ("Portuguese-Brazil"). + + Returns the information for the given language or @NULL if this language + is unknown. Note that even if the returned pointer is valid, the caller should + @e not delete it. + + @sa GetLanguageInfo() + */ + static wxLanguageInfo * FindLanguageInfo(const wxString& locale); + + /** + Returns the canonical form of current locale name. Canonical form is the + one that is used on UNIX systems: it is a two- or five-letter string in xx or + xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of + the country. Examples are "en", "en_GB", "en_US" or "fr_FR". + + This form is internally used when looking up message catalogs. + + Compare GetSysName(). + */ + wxString GetCanonicalName(); + + /** + Returns the header value for header @e header. The search for @e header is case + sensitive. If an @e domain + is passed, this domain is searched. Else all domains will be searched until a + header has been found. + The return value is the value of the header if found. Else this will be empty. + */ + wxString GetHeaderValue(const wxString& header, + const wxString& domain = wxEmptyString); + + /** + Returns wxLanguage constant of current language. + Note that you can call this function only if you used the form of + Init() that takes wxLanguage argument. + */ + int GetLanguage(); + + /** + Returns a pointer to wxLanguageInfo structure containing information about the + given language or @NULL if this language is unknown. Note that even if the + returned pointer is valid, the caller should @e not delete it. + + See AddLanguage() for the wxLanguageInfo + description. + + As with Init(), @c wxLANGUAGE_DEFAULT has the + special meaning if passed as an argument to this function and in this case the + result of GetSystemLanguage() is used. + */ + static wxLanguageInfo * GetLanguageInfo(int lang); + + /** + Returns English name of the given language or empty string if this + language is unknown. + + See GetLanguageInfo() for a remark about + special meaning of @c wxLANGUAGE_DEFAULT. + */ + static wxString GetLanguageName(int lang); + + /** + Returns the locale name as passed to the constructor or + Init(). This is full, human-readable name, + e.g. "English" or "French". + */ + const wxString GetLocale(); + + /** + Returns the current short name for the locale (as given to the constructor or + the Init() function). + */ + const wxString GetName(); + + //@{ + /** + Retrieves the translation for a string in all loaded domains unless the szDomain + parameter is specified (and then only this catalog/domain is searched). + + Returns original string if translation is not available + (in this case an error message is generated the first time + a string is not found; use wxLogNull to suppress it). + + The second form is used when retrieving translation of string that has + different singular and plural form in English or different plural forms in some + other language. It takes two extra arguments: @e origString + parameter must contain the singular form of the string to be converted. + It is also used as the key for the search in the catalog. + The @e origString2 parameter is the plural form (in English). + The parameter @e n is used to determine the plural form. If no + message catalog is found @e origString is returned if 'n == 1', + otherwise @e origString2. + See GNU gettext manual for additional information on plural forms handling. + + This method is called by the wxGetTranslation + function and _ macro. + + @remarks Domains are searched in the last to first order, i.e. catalogs + added later override those added before. + */ + const wxString GetString(const wxString& origString, + const wxString& domain = wxEmptyString); + const wxString GetString(const wxString& origString, + const wxString& origString2, + size_t n, + const wxString& domain = @NULL); + //@} + + /** + Returns current platform-specific locale name as passed to setlocale(). + + Compare GetCanonicalName(). + */ + wxString GetSysName(); + + /** + Tries to detect the user's default font encoding. + Returns wxFontEncoding value or + @b wxFONTENCODING_SYSTEM if it couldn't be determined. + */ + static wxFontEncoding GetSystemEncoding(); + + /** + Tries to detect the name of the user's default font encoding. This string isn't + particularly useful for the application as its form is platform-dependent and + so you should probably use + GetSystemEncoding() instead. + + Returns a user-readable string value or an empty string if it couldn't be + determined. + */ + static wxString GetSystemEncodingName(); + + /** + Tries to detect the user's default language setting. + Returns wxLanguage value or + @b wxLANGUAGE_UNKNOWN if the language-guessing algorithm failed. + */ + static int GetSystemLanguage(); + + //@{ + /** + The second form is deprecated, use the first one unless you know what you are + doing. + + @param language + wxLanguage identifier of the locale. + wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's default + language (see GetSystemLanguage). + + @param flags + Combination of the following: + + + wxLOCALE_LOAD_DEFAULT + + + Load the message catalog + for the given locale containing the translations of standard wxWidgets messages + automatically. + + wxLOCALE_CONV_ENCODING + + + Automatically convert message + catalogs to platform's default encoding. Note that it will do only basic + conversion between well-known pair like iso8859-1 and windows-1252 or + iso8859-2 and windows-1250. See Writing non-English applications for detailed + description of this behaviour. Note that this flag is meaningless in Unicode + build. + + @param name + The name of the locale. Only used in diagnostic messages. + + @param short + The standard 2 letter locale abbreviation; it is used as the + directory prefix when looking for the message catalog files. + + @param locale + The parameter for the call to setlocale(). Note that it is + platform-specific. + + @param bLoadDefault + May be set to @false to prevent loading of the message catalog + for the given locale containing the translations of standard wxWidgets messages. + This parameter would be rarely used in normal circumstances. + + @param bConvertEncoding + May be set to @true to do automatic conversion of message + catalogs to platform's native encoding. Note that it will do only basic + conversion between well-known pair like iso8859-1 and windows-1252 or + iso8859-2 and windows-1250. + See Writing non-English applications for detailed + description of this behaviour. + */ + bool Init(int language = wxLANGUAGE_DEFAULT, + int flags = + wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); + bool Init(const wxString& name, + const wxString& short = wxEmptyString, + const wxString& locale = wxEmptyString, + bool bLoadDefault = @true, + bool bConvertEncoding = @false); + //@} + + /** + Check whether the operating system and/or C run time environment supports + this locale. For example in Windows 2000 and Windows XP, support for many + locales is not installed by default. Returns @true if the locale is + supported. + + The argument @e lang is the wxLanguage identifier. To obtain this for a + given a two letter ISO language code, use + FindLanguageInfo() to obtain its + wxLanguageInfo structure. See AddLanguage() for + the wxLanguageInfo description. + + This function is new since wxWidgets version 2.7.1. + */ + static bool IsAvailable(int lang); + + /** + Check if the given catalog is loaded, and returns @true if it is. + + According to GNU gettext tradition, each catalog + normally corresponds to 'domain' which is more or less the application name. + + See also: AddCatalog() + */ + bool IsLoaded(const char* domain); + + /** + Returns @true if the locale could be set successfully. + */ +#define bool IsOk() /* implementation is private */ + + /** + See @ref overview_languagecodes "list of recognized language constants". + These constants may be used to specify the language + in Init() and are returned by + GetSystemLanguage(): + */ +}; + + +/** + @class wxXLocale + @wxheader{intl.h} + + + wxXLocale::wxXLocale + wxXLocale::GetCLocale + wxXLocale::IsOk + + + Introduction + + This class represents a locale object used by so-called xlocale API. Unlike + wxLocale it doesn't provide any non-trivial operations but + simply provides a portable wrapper for POSIX @c locale_t type. It exists + solely to be provided as an argument to various @c wxFoo_l() functions + which are the extensions of the standard locale-dependent functions (hence the + name xlocale). These functions do exactly the same thing as the corresponding + standard @c foo() except that instead of using the global program locale + they use the provided wxXLocale object. For example, if the user runs the + program in French locale, the standard @c printf() function will output + floating point numbers using decimal comma instead of decimal period. If the + program needs to format a floating-point number in a standard format it can + use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it. + Conversely, if a program wanted to output the number in French locale, even if + the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH). + + + Availability + + This class is fully implemented only under the platforms where xlocale POSIX + API or equivalent is available. Currently the xlocale API is available under + most of the recent Unix systems (including Linux, various BSD and Mac OS X) and + Microsoft Visual C++ standard library provides a similar API starting from + version 8 (Visual Studio 2005). + + If neither POSIX API nor Microsoft proprietary equivalent are available, this + class is still available but works in degraded mode: the only supported locale + is the C one and attempts to create wxXLocale object for any other locale will + fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to + test if full xlocale API is available or only skeleton C locale support is + present. + + Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if + @c wxUSE_XLOCALE was set to 0 during the library compilation. + + + Locale-dependent functions + + Currently the following @c _l-functions are available: + + Character classification functions: @c wxIsxxx_l(), e.g. + @c wxIsalpha_l(), @c wxIslower_l() and all the others. + Character transformation functions: @c wxTolower_l() and + @c wxToupper_l() + + We hope to provide many more functions (covering numbers, time and formatted + IO) in the near future. + + @library{wxbase} + @category{FIXME} + + @seealso + wxLocale +*/ +class wxXLocale +{ +public: + //@{ + /** + Creates the locale object corresponding to the specified locale string. The + locale string is system-dependent, use constructor taking wxLanguage for better + portability. + */ + wxLocale(); + wxLocale(wxLanguage lang); + wxLocale(const char * loc); + //@} + + /** + This class is fully implemented only under the platforms where xlocale POSIX + API or equivalent is available. Currently the xlocale API is available under + most of the recent Unix systems (including Linux, various BSD and Mac OS X) and + Microsoft Visual C++ standard library provides a similar API starting from + version 8 (Visual Studio 2005). + + If neither POSIX API nor Microsoft proprietary equivalent are available, this + class is still available but works in degraded mode: the only supported locale + is the C one and attempts to create wxXLocale object for any other locale will + fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to + test if full xlocale API is available or only skeleton C locale support is + present. + + Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if + @c wxUSE_XLOCALE was set to 0 during the library compilation. + */ + + + /** + Returns the global object representing the "C" locale. For an even shorter + access to this object a global @c wxCLocale variable (implemented as a + macro) is provided and can be used instead of calling this method. + */ + static wxXLocale GetCLocale(); + + /** + This class represents a locale object used by so-called xlocale API. Unlike + wxLocale it doesn't provide any non-trivial operations but + simply provides a portable wrapper for POSIX @c locale_t type. It exists + solely to be provided as an argument to various @c wxFoo_l() functions + which are the extensions of the standard locale-dependent functions (hence the + name xlocale). These functions do exactly the same thing as the corresponding + standard @c foo() except that instead of using the global program locale + they use the provided wxXLocale object. For example, if the user runs the + program in French locale, the standard @c printf() function will output + floating point numbers using decimal comma instead of decimal period. If the + program needs to format a floating-point number in a standard format it can + use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it. + Conversely, if a program wanted to output the number in French locale, even if + the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH). + */ + + + /** + Returns @true if this object is initialized, i.e. represents a valid locale + or + @false otherwise. + */ +#define bool IsOk() /* implementation is private */ + + /** + Currently the following @c _l-functions are available: + + Character classification functions: @c wxIsxxx_l(), e.g. + @c wxIsalpha_l(), @c wxIslower_l() and all the others. + Character transformation functions: @c wxTolower_l() and + @c wxToupper_l() + + We hope to provide many more functions (covering numbers, time and formatted + IO) in the near future. + + @sa wxLocale + */ +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + This macro is identical to _ but for the plural variant + of wxGetTranslation. +*/ +#define const wxString wxPLURAL(const wxString& sing, + const wxString& plur, + size_t n) /* implementation is private */ + +/** + This macro doesn't do anything in the program code -- it simply expands to the + value of its argument. + + However it does have a purpose which is to mark the literal strings for the + extraction into the message catalog created by @c xgettext program. Usually + this is achieved using _ but that macro not only marks + the string for extraction but also expands into a + wxGetTranslation function call which means that it + cannot be used in some situations, notably for static array + initialization. + + Here is an example which should make it more clear: suppose that you have a + static array of strings containing the weekday names and which have to be + translated (note that it is a bad example, really, as + wxDateTime already can be used to get the localized week + day names already). If you write + @code + static const char * const weekdays[] = { _("Mon"), ..., _("Sun") }; + ... + // use weekdays[n] as usual + @endcode + + the code wouldn't compile because the function calls are forbidden in the array + initializer. So instead you should do + @code + static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., + wxTRANSLATE("Sun") }; + ... + // use wxGetTranslation(weekdays[n]) + @endcode + + here. + + Note that although the code @b would compile if you simply omit + wxTRANSLATE() in the above, it wouldn't work as expected because there would be + no translations for the weekday names in the program message catalog and + wxGetTranslation wouldn't find them. +*/ +#define const wxChar * wxTRANSLATE(const char * s) /* implementation is private */ + +/** + This macro expands into a call to wxGetTranslation + function, so it marks the message for the extraction by @c xgettext just as + wxTRANSLATE does, but also returns the translation of + the string for the current locale during execution. + + Don't confuse this macro with _T! +*/ +#define const wxString _(const wxString& s) /* implementation is private */ + +//@{ +/** + This function returns the translation of string @e str in the current + locale. If the string is not found in any of the loaded + message catalogs (see @ref overview_internationalization "internationalization + overview"), the + original string is returned. In debug build, an error message is logged -- this + should help to find the strings which were not yet translated. If + @e domain is specified then only that domain/catalog is searched + for a matching string. As this function + is used very often, an alternative (and also common in Unix world) syntax is + provided: the _ macro is defined to do the same thing + as wxGetTranslation. + + The second form is used when retrieving translation of string that has + different singular and plural form in English or different plural forms in some + other language. It takes two extra arguments: as above, @e str + parameter must contain the singular form of the string to be converted and + is used as the key for the search in the catalog. The @e strPlural parameter + is the plural form (in English). The parameter @e n is used to determine the + plural form. If no message catalog is found @e str is returned if 'n == 1', + otherwise @e strPlural. + + See GNU gettext manual + for additional information on plural forms handling. For a shorter alternative + see the wxPLURAL macro. + + Both versions call wxLocale::GetString. + + Note that this function is not suitable for literal strings in Unicode + builds, since the literal strings must be enclosed into + _T or wxT macro which makes them + unrecognised by @c xgettext, and so they are not extracted to the message + catalog. Instead, use the _ and + wxPLURAL macro for all literal strings. +*/ +const wxString wxGetTranslation(const wxString& str, + const wxString& domain = wxEmptyString); + const wxString wxGetTranslation(const wxString& str, + const wxString& strPlural, + size_t n, + const wxString& domain = wxEmptyString); +//@} + diff --git a/interface/ipc.h b/interface/ipc.h new file mode 100644 index 0000000000..1130dc32b1 --- /dev/null +++ b/interface/ipc.h @@ -0,0 +1,357 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ipc.h +// Purpose: documentation for wxConnection class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxConnection + @wxheader{ipc.h} + + A wxConnection object represents the connection between a client + and a server. It is created by making a connection using a + wxClient object, or by the acceptance of a + connection by a wxServer object. The + bulk of a DDE-like (Dynamic Data Exchange) conversation is + controlled by calling members in a @b wxConnection object or + by overriding its members. The actual DDE-based implementation + using wxDDEConnection is available on Windows only, but a + platform-independent, socket-based version of this API is + available using wxTCPConnection, which has the same API. + + An application should normally derive a new connection class from + wxConnection, in order to override the communication event + handlers to do something interesting. + + @library{wxbase} + @category{FIXME} + + @seealso + wxClient, wxServer, @ref overview_ipcoverview "Interprocess communications + overview" +*/ +class wxConnection : public wxObject +{ +public: + //@{ + /** + Constructs a connection object. If no user-defined connection + object is to be derived from wxConnection, then the constructor + should not be called directly, since the default connection + object will be provided on requesting (or accepting) a + connection. However, if the user defines his or her own derived + connection object, the wxServer::OnAcceptConnection + and/or wxClient::OnMakeConnection + members should be replaced by functions which construct the new + connection object. + + If the arguments of the wxConnection constructor are void then + the wxConnection object manages its own connection buffer, + allocating memory as needed. A programmer-supplied buffer cannot + be increased if necessary, and the program will assert if it is + not large enough. The programmer-supplied buffer is included + mainly for backwards compatibility. + */ + wxConnection(); + wxConnection(void* buffer, size_t size); + //@} + + //@{ + /** + Called by the server application to advise the client of a change + in the data associated with the given item. Causes the client + connection's OnAdvise() member + to be called. Returns @true if successful. + */ + bool Advise(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Advise(const wxString& item, const char* data); + bool Advise(const wxString& item, const wchar_t* data); + bool Advise(const wxString& item, const wxString data); + //@} + + /** + Called by the client or server application to disconnect from the + other program; it causes the OnDisconnect() + message to be sent to the corresponding connection object in the + other program. Returns @true if successful or already disconnected. + The application that calls @b Disconnect must explicitly delete + its side of the connection. + */ + bool Disconnect(); + + //@{ + /** + Called by the client application to execute a command on the + server. Can also be used to transfer arbitrary data to the server + (similar to Poke() in + that respect). Causes the server connection's OnExec() + member to be called. Returns @true if successful. + */ + bool Execute(const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Execute(const char* data); + bool Execute(const wchar_t* data); + bool Execute(const wxString data); + //@} + + /** + Message sent to the client application when the server notifies + it of a change in the data associated with the given item, using + Advise(). + */ + virtual bool OnAdvise(const wxString& topic, + const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the client or server application when the other + application notifies it to end the connection. The default + behaviour is to delete the connection object and return @true, so + applications should generally override @b OnDisconnect + (finally calling the inherited method as well) so that they know + the connection object is no longer available. + */ + virtual bool OnDisconnect(); + + /** + Message sent to the server application when the client notifies + it to execute the given data, using Execute(). + Note that there is no item associated with this message. + */ + virtual bool OnExec(const wxString& topic, const wxString& data); + + /** + Message sent to the server application when the client notifies it to + accept the given data. + */ + virtual bool OnPoke(const wxString& topic, const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the server application when the client calls + Request(). The + server's OnRequest() method + should respond by returning a character string, or @NULL to + indicate no data, and setting *size. The character string must of + course persist after the call returns. + */ + virtual const void* OnRequest(const wxString& topic, + const wxString& item, + size_t * size, + wxIPCFormat format); + + /** + Message sent to the server application by the client, when the client + wishes to start an 'advise loop' for the given topic and item. The + server can refuse to participate by returning @false. + */ + virtual bool OnStartAdvise(const wxString& topic, + const wxString& item); + + /** + Message sent to the server application by the client, when the client + wishes to stop an 'advise loop' for the given topic and item. The + server can refuse to stop the advise loop by returning @false, although + this doesn't have much meaning in practice. + */ + virtual bool OnStopAdvise(const wxString& topic, + const wxString& item); + + //@{ + /** + Called by the client application to poke data into the server. + Can be used to transfer arbitrary data to the server. Causes the + server connection's OnPoke() member to + be called. If size is -1 the size is computed from the string + length of data. + + Returns @true if successful. + */ + bool Poke(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Poke(const wxString& item, const char* data); + bool Poke(const wxString& item, const wchar_t* data); + bool Poke(const wxString& item, const wxString data); + //@} + + /** + Called by the client application to request data from the server. + Causes the server connection's OnRequest() + member to be called. Size may be @NULL or a pointer to a variable + to receive the size of the requested item. + + Returns a character string (actually a pointer to the + connection's buffer) if successful, @NULL otherwise. This buffer + does not need to be deleted. + */ + const void* Request(const wxString& item, size_t * size, + wxIPCFormat format = wxIPC_TEXT); + + /** + Called by the client application to ask if an advise loop can be + started with the server. Causes the server connection's + OnStartAdvise() + member to be called. Returns @true if the server okays it, @false + otherwise. + */ + bool StartAdvise(const wxString& item); + + /** + Called by the client application to ask if an advise loop can be + stopped. Causes the server connection's OnStopAdvise() + member to be called. Returns @true if the server okays it, @false + otherwise. + */ + bool StopAdvise(const wxString& item); +}; + + +/** + @class wxClient + @wxheader{ipc.h} + + A wxClient object represents the client part of a client-server + DDE-like (Dynamic Data Exchange) conversation. The actual + DDE-based implementation using wxDDEClient is available on Windows + only, but a platform-independent, socket-based version of this + API is available using wxTCPClient, which has the same API. + + To create a client which can communicate with a suitable server, + you need to derive a class from wxConnection and another from + wxClient. The custom wxConnection class will intercept + communications in a 'conversation' with a server, and the custom + wxClient is required so that a user-overridden + wxClient::OnMakeConnection + member can return a wxConnection of the required class, when a + connection is made. Look at the IPC sample and the + @ref overview_ipcoverview "Interprocess communications overview" for + an example of how to do this. + + @library{wxbase} + @category{FIXME} + + @seealso + wxServer, wxConnection, @ref overview_ipcoverview "Interprocess communications + overview" +*/ +class wxClient : public wxObject +{ +public: + /** + Constructs a client object. + */ + wxClient(); + + /** + Tries to make a connection with a server by host (machine name + under UNIX - use 'localhost' for same machine; ignored when using + native DDE in Windows), service name and topic string. If the + server allows a connection, a wxConnection object will be + returned. The type of wxConnection returned can be altered by + overriding the + OnMakeConnection() + member to return your own derived connection object. + + Under Unix, the service name may be either an integer port + identifier in which case an Internet domain socket will be used + for the communications, or a valid file name (which shouldn't + exist and will be deleted afterwards) in which case a Unix domain + socket is created. + + @b SECURITY NOTE: Using Internet domain sockets if extremely + insecure for IPC as there is absolutely no access control for + them, use Unix domain sockets whenever possible! + */ + wxConnectionBase * MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); + + /** + Called by MakeConnection(), by + default this simply returns a new wxConnection object. Override + this method to return a wxConnection descendant customised for the + application. + + The advantage of deriving your own connection class is that it + will enable you to intercept messages initiated by the server, + such as wxConnection::OnAdvise. You + may also want to store application-specific data in instances of + the new class. + */ + wxConnectionBase * OnMakeConnection(); + + /** + Returns @true if this is a valid host name, @false otherwise. This always + returns @true under MS Windows. + */ + bool ValidHost(const wxString& host); +}; + + +/** + @class wxServer + @wxheader{ipc.h} + + A wxServer object represents the server part of a client-server + DDE-like (Dynamic Data Exchange) conversation. The actual + DDE-based implementation using wxDDEServer is available on Windows + only, but a platform-independent, socket-based version of this + API is available using wxTCPServer, which has the same API. + + To create a server which can communicate with a suitable client, + you need to derive a class from wxConnection and another from + wxServer. The custom wxConnection class will intercept + communications in a 'conversation' with a client, and the custom + wxServer is required so that a user-overridden wxServer::OnAcceptConnection + member can return a wxConnection of the required class, when a + connection is made. Look at the IPC sample and the @ref overview_ipcoverview + "Interprocess communications overview" for + an example of how to do this. + + @library{wxbase} + @category{FIXME} + + @seealso + wxClient, wxConnection, IPC, overview +*/ +class wxServer +{ +public: + /** + Constructs a server object. + */ + wxServer(); + + /** + Registers the server using the given service name. Under Unix, + the service name may be either an integer port identifier in + which case an Internet domain socket will be used for the + communications, or a valid file name (which shouldn't exist and + will be deleted afterwards) in which case a Unix domain socket is + created. @false is returned if the call failed (for example, the + port number is already in use). + */ + bool Create(const wxString& service); + + /** + When a client calls @b MakeConnection, the server receives the + message and this member is called. The application should derive a + member to intercept this message and return a connection object of + either the standard wxConnection type, or (more likely) of a + user-derived type. + + If the topic is @b STDIO, the application may wish to refuse the + connection. Under UNIX, when a server is created the + OnAcceptConnection message is always sent for standard input and + output, but in the context of DDE messages it doesn't make a lot + of sense. + */ + virtual wxConnectionBase * OnAcceptConnection(const wxString& topic); +}; diff --git a/interface/joystick.h b/interface/joystick.h new file mode 100644 index 0000000000..a97eb74aec --- /dev/null +++ b/interface/joystick.h @@ -0,0 +1,273 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: joystick.h +// Purpose: documentation for wxJoystick class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxJoystick + @wxheader{joystick.h} + + wxJoystick allows an application to control one or more joysticks. + + @library{wxadv} + @category{FIXME} + + @seealso + wxJoystickEvent +*/ +class wxJoystick : public wxObject +{ +public: + /** + Constructor. @e joystick may be one of wxJOYSTICK1, wxJOYSTICK2, indicating the + joystick + controller of interest. + */ + wxJoystick(int joystick = wxJOYSTICK1); + + /** + Destroys the wxJoystick object. + */ + ~wxJoystick(); + + //@{ + /** + Returns the state of the specified joystick button. + + @param id + The button id to report, from 0 to GetNumberButtons() - 1 + */ + int GetButtonState(); + bool GetButtonState(unsigned id); + //@} + + /** + Returns the manufacturer id. + */ + int GetManufacturerId(); + + /** + Returns the movement threshold, the number of steps outside which the joystick + is deemed to have + moved. + */ + int GetMovementThreshold(); + + /** + Returns the number of axes for this joystick. + */ + int GetNumberAxes(); + + /** + Returns the number of buttons for this joystick. + */ + int GetNumberButtons(); + + /** + Returns the number of joysticks currently attached to the computer. + */ + static int GetNumberJoysticks(); + + /** + Returns the point-of-view position, expressed in continuous, one-hundredth of a + degree units. + Returns -1 on error. + */ + int GetPOVCTSPosition(); + + /** + Returns the point-of-view position, expressed in continuous, one-hundredth of a + degree units, + but limited to return 0, 9000, 18000 or 27000. + Returns -1 on error. + */ + int GetPOVPosition(); + + /** + Returns the maximum polling frequency. + */ + int GetPollingMax(); + + /** + Returns the minimum polling frequency. + */ + int GetPollingMin(); + + //@{ + /** + Returns the position of the specified joystick axis. + + @param axis + The joystick axis to report, from 0 to GetNumberAxes() - 1. + */ + wxPoint GetPosition(); + int GetPosition(unsigned axis); + //@} + + /** + Returns the product id for the joystick. + */ + int GetProductId(); + + /** + Returns the product name for the joystick. + */ + wxString GetProductName(); + + /** + Returns the maximum rudder position. + */ + int GetRudderMax(); + + /** + Returns the minimum rudder position. + */ + int GetRudderMin(); + + /** + Returns the rudder position. + */ + int GetRudderPosition(); + + /** + Returns the maximum U position. + */ + int GetUMax(); + + /** + Returns the minimum U position. + */ + int GetUMin(); + + /** + Gets the position of the fifth axis of the joystick, if it exists. + */ + int GetUPosition(); + + /** + Returns the maximum V position. + */ + int GetVMax(); + + /** + Returns the minimum V position. + */ + int GetVMin(); + + /** + Gets the position of the sixth axis of the joystick, if it exists. + */ + int GetVPosition(); + + /** + Returns the maximum x position. + */ + int GetXMax(); + + /** + Returns the minimum x position. + */ + int GetXMin(); + + /** + Returns the maximum y position. + */ + int GetYMax(); + + /** + Returns the minimum y position. + */ + int GetYMin(); + + /** + Returns the maximum z position. + */ + int GetZMax(); + + /** + Returns the minimum z position. + */ + int GetZMin(); + + /** + Returns the z position of the joystick. + */ + int GetZPosition(); + + /** + Returns @true if the joystick has a point of view control. + */ +#define bool HasPOV() /* implementation is private */ + + /** + Returns @true if the joystick point-of-view supports discrete values (centered, + forward, backward, left, and right). + */ + bool HasPOV4Dir(); + + /** + Returns @true if the joystick point-of-view supports continuous degree bearings. + */ +#define bool HasPOVCTS() /* implementation is private */ + + /** + Returns @true if there is a rudder attached to the computer. + */ + bool HasRudder(); + + /** + Returns @true if the joystick has a U axis. + */ +#define bool HasU() /* implementation is private */ + + /** + Returns @true if the joystick has a V axis. + */ +#define bool HasV() /* implementation is private */ + + /** + Returns @true if the joystick has a Z axis. + */ +#define bool HasZ() /* implementation is private */ + + /** + Returns @true if the joystick is functioning. + */ +#define bool IsOk() /* implementation is private */ + + /** + Releases the capture set by @b SetCapture. + + @returns @true if the capture release succeeded. + + @sa SetCapture(), wxJoystickEvent + */ + bool ReleaseCapture(); + + /** + Sets the capture to direct joystick events to @e win. + + @param win + The window that will receive joystick events. + + @param pollingFreq + If zero, movement events are sent when above the + threshold. If greater than zero, events are received every pollingFreq + milliseconds. + + @returns @true if the capture succeeded. + + @sa ReleaseCapture(), wxJoystickEvent + */ + bool SetCapture(wxWindow* win, int pollingFreq = 0); + + /** + Sets the movement threshold, the number of steps outside which the joystick is + deemed to have + moved. + */ + void SetMovementThreshold(int threshold); +}; diff --git a/interface/layout.h b/interface/layout.h new file mode 100644 index 0000000000..7b9279fec1 --- /dev/null +++ b/interface/layout.h @@ -0,0 +1,308 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: layout.h +// Purpose: documentation for wxIndividualLayoutConstraint class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIndividualLayoutConstraint + @wxheader{layout.h} + + 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. + + @library{wxcore} + @category{winlayout} + + @seealso + @ref overview_constraintsoverview "Overview and examples", wxLayoutConstraints, + wxWindow::SetConstraints. +*/ +class wxIndividualLayoutConstraint : public wxObject +{ +public: + /** + Constructor. Not used by the end-user. + */ + wxIndividualLayoutConstraint(); + + /** + 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. + */ + void Above(wxWindow * otherWin, int margin = 0); + + /** + Constrains this edge or dimension to be the given absolute value. + */ + void Absolute(int 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 @e 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. + */ +#define void AsIs() /* implementation is private */ + + /** + 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. + */ + void Below(wxWindow * otherWin, int margin = 0); + + /** + The @e wxEdge enumerated type specifies the type of edge or dimension of a + window. + + wxLeft + + + The left edge. + + wxTop + + + The top edge. + + wxRight + + + The right edge. + + wxBottom + + + The bottom edge. + + wxCentreX + + + The x-coordinate of the centre of the window. + + wxCentreY + + + The y-coordinate of the centre of the window. + + The @e wxRelationship enumerated type specifies the relationship that + this edge or dimension has with another specified edge or dimension. Normally, + the user + doesn't use these directly because functions such as @e Below and @e RightOf + are a convenience + for using the more general @e Set function. + + wxUnconstrained + + + The edge or dimension is unconstrained (the default for edges. + + wxAsIs + + + The edge or dimension is to be taken from the current window position or size + (the + default for dimensions. + + wxAbove + + + The edge should be above another edge. + + wxBelow + + + The edge should be below another edge. + + wxLeftOf + + + The edge should be to the left of another edge. + + wxRightOf + + + The edge should be to the right of another edge. + + wxSameAs + + + The edge or dimension should be the same as another edge or dimension. + + wxPercentOf + + + The edge or dimension should be a percentage of another edge or dimension. + + wxAbsolute + + + The edge or dimension should be a given absolute value. + */ + + + /** + 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. + */ + void LeftOf(wxWindow * otherWin, int margin = 0); + + /** + Constrains this edge or dimension to be to a percentage of the given window, + with an + optional margin. + */ + void PercentOf(wxWindow * otherWin, wxEdge edge, int per); + + /** + 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. + */ + void RightOf(wxWindow * otherWin, int margin = 0); + + /** + Constrains this edge or dimension to be to the same as the edge of the given + window, with an + optional margin. + */ + void SameAs(wxWindow * otherWin, wxEdge edge, int margin = 0); + + /** + Sets the properties of the constraint. Normally called by one of the convenience + functions such as Above, RightOf, SameAs. + */ +#define void Set(wxRelationship rel, wxWindow * otherWin, + wxEdge otherEdge, int value = 0, + int margin = 0) /* implementation is private */ + + /** + Sets this edge or dimension to be unconstrained, that is, dependent on + other edges and dimensions from which this value can be deduced. + */ + void Unconstrained(); +}; + + +/** + @class wxLayoutConstraints + @wxheader{layout.h} + + @b 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. + + @b left: represents the left hand edge of the window + @b right: represents the right hand edge of the window + @b top: represents the top edge of the window + @b bottom: represents the bottom edge of the window + @b width: represents the width of the window + @b height: represents the height of the window + @b centreX: represents the horizontal centre point of the window + @b centreY: represents the vertical centre point of the window + + 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 @e width and @e 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. + + @b wxPerl note: In wxPerl the constraints are accessed as + + @code + constraint = Wx::LayoutConstraints-new(); + constraint-centreX-AsIs(); + constraint-centreY-Unconstrained(); + @endcode + + + @library{wxcore} + @category{winlayout} + + @seealso + @ref overview_constraintsoverview "Overview and examples", + wxIndividualLayoutConstraint, wxWindow::SetConstraints +*/ +class wxLayoutConstraints : public wxObject +{ +public: + /** + Constructor. + */ + wxLayoutConstraints(); + + /** + wxIndividualLayoutConstraint bottom + + Constraint for the bottom edge. + */ + + + /** + wxIndividualLayoutConstraint centreX + + Constraint for the horizontal centre point. + */ + + + /** + wxIndividualLayoutConstraint centreY + + Constraint for the vertical centre point. + */ + + + /** + wxIndividualLayoutConstraint height + + Constraint for the height. + */ + + + /** + wxIndividualLayoutConstraint left + + Constraint for the left-hand edge. + */ + + + /** + wxIndividualLayoutConstraint right + + Constraint for the right-hand edge. + */ + + + /** + wxIndividualLayoutConstraint top + + Constraint for the top edge. + */ + + + /** + wxIndividualLayoutConstraint width + + Constraint for the width. + */ +}; diff --git a/interface/laywin.h b/interface/laywin.h new file mode 100644 index 0000000000..4dfe52b28a --- /dev/null +++ b/interface/laywin.h @@ -0,0 +1,429 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: laywin.h +// Purpose: documentation for wxLayoutAlgorithm class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxLayoutAlgorithm + @wxheader{laywin.h} + + wxLayoutAlgorithm implements layout of subwindows in MDI or SDI frames. + It sends a wxCalculateLayoutEvent event + to children of the frame, asking them for information about + their size. For MDI parent frames, the algorithm allocates + the remaining space to the MDI client window (which contains the MDI child + frames). + For SDI (normal) frames, a 'main' window is specified as taking up the + remaining space. + + Because the event system is used, this technique can be applied to any windows, + which are not necessarily 'aware' of the layout classes (no virtual functions + in wxWindow refer to wxLayoutAlgorithm or its events). However, you + may wish to use wxSashLayoutWindow for your subwindows + since this class provides handlers for the required events, and accessors + to specify the desired size of the window. The sash behaviour in the base class + can be used, optionally, to make the windows user-resizable. + + wxLayoutAlgorithm is typically used in IDE (integrated development environment) + applications, + where there are several resizable windows in addition to the MDI client window, + or + other primary editing window. Resizable windows might include toolbars, a + project + window, and a window for displaying error and warning messages. + + When a window receives an OnCalculateLayout event, it should call SetRect in + the given event object, to be the old supplied rectangle minus whatever space + the + window takes up. It should also set its own size accordingly. + wxSashLayoutWindow::OnCalculateLayout generates an OnQueryLayoutInfo event + which it sends to itself to determine the orientation, alignment and size of + the window, + which it gets from internal member variables set by the application. + + The algorithm works by starting off with a rectangle equal to the whole frame + client area. + It iterates through the frame children, generating OnCalculateLayout events + which subtract + the window size and return the remaining rectangle for the next window to + process. It + is assumed (by wxSashLayoutWindow::OnCalculateLayout) that a window stretches + the full dimension + of the frame client, according to the orientation it specifies. For example, a + horizontal window + will stretch the full width of the remaining portion of the frame client area. + In the other orientation, the window will be fixed to whatever size was + specified by + OnQueryLayoutInfo. An alignment setting will make the window 'stick' to the + left, top, right or + bottom of the remaining client area. This scheme implies that order of window + creation is important. + Say you wish to have an extra toolbar at the top of the frame, a project window + to the left of + the MDI client window, and an output window above the status bar. You should + therefore create + the windows in this order: toolbar, output window, project window. This ensures + that the toolbar and + output window take up space at the top and bottom, and then the remaining + height in-between is used for + the project window. + + wxLayoutAlgorithm is quite independent of the way in which + OnCalculateLayout chooses to interpret a window's size and alignment. Therefore + you + could implement a different window class with a new OnCalculateLayout event + handler, + that has a more sophisticated way of laying out the windows. It might allow + specification of whether stretching occurs in the specified orientation, for + example, + rather than always assuming stretching. (This could, and probably should, be + added to the existing + implementation). + + @e Note: wxLayoutAlgorithm has nothing to do with wxLayoutConstraints. It is an + alternative + way of specifying layouts for which the normal constraint system is unsuitable. + + @library{wxadv} + @category{winlayout} + + @seealso + wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview "Event + handling overview" +*/ +class wxLayoutAlgorithm : public wxObject +{ +public: + /** + Default constructor. + */ + wxLayoutAlgorithm(); + + /** + Destructor. + */ + ~wxLayoutAlgorithm(); + + /** + Lays out the children of a normal frame. @e mainWindow is set to occupy the + remaining space. + + This function simply calls LayoutWindow(). + */ + bool LayoutFrame(wxFrame* frame, wxWindow* mainWindow = @NULL); + + /** + Lays out the children of an MDI parent frame. If @e rect is non-@NULL, the + given rectangle will be used as a starting point instead of the frame's client + area. + + The MDI client window is set to occupy the remaining space. + */ + bool LayoutMDIFrame(wxMDIParentFrame* frame, wxRect* rect = @NULL); + + /** + Lays out the children of a normal frame or other window. + + @e mainWindow is set to occupy the remaining space. If this is not specified, + then + the last window that responds to a calculate layout event in query mode will + get the remaining space + (that is, a non-query OnCalculateLayout event will not be sent to this window + and the window will be set + to the remaining size). + */ + bool LayoutWindow(wxWindow* parent, wxWindow* mainWindow = @NULL); +}; + + +/** + @class wxSashLayoutWindow + @wxheader{laywin.h} + + wxSashLayoutWindow responds to OnCalculateLayout events generated + by wxLayoutAlgorithm. It allows the + application to use simple accessors to specify how the window should be + laid out, rather than having to respond to events. The fact that + the class derives from wxSashWindow allows sashes to be used if required, + to allow the windows to be user-resizable. + + The documentation for wxLayoutAlgorithm explains + the purpose of this class in more detail. + + @library{wxadv} + @category{miscwnd} + + @seealso + wxLayoutAlgorithm, wxSashWindow, @ref overview_eventhandlingoverview "Event + handling overview" +*/ +class wxSashLayoutWindow : public wxSashWindow +{ +public: + //@{ + /** + Constructs a sash layout window, which can be a child of a frame, dialog or any + other non-control window. + + @param parent + Pointer to a parent window. + + @param id + Window identifier. If -1, will automatically create an identifier. + + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxSashLayoutWindows + should generate a default position for the window. If using the + wxSashLayoutWindow class directly, supply + an actual position. + + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that wxSashLayoutWindows + should generate a default size for the window. + + @param style + Window style. For window styles, please see wxSashLayoutWindow. + + @param name + Window name. + */ + wxSashLayoutWindow(); + wxSashLayoutWindow(wxSashLayoutWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLIP_CHILDREN | wxSW_3D, + const wxString& name = "layoutWindow"); + //@} + + /** + Initializes a sash layout window, which can be a child of a frame, dialog or + any other non-control window. + + @param parent + Pointer to a parent window. + + @param id + Window identifier. If -1, will automatically create an identifier. + + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxSashLayoutWindows + should generate a default position for the window. If using the + wxSashLayoutWindow class directly, supply + an actual position. + + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that wxSashLayoutWindows + should generate a default size for the window. + + @param style + Window style. For window styles, please see wxSashLayoutWindow. + + @param name + Window name. + */ + bool Create(wxSashLayoutWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLIP_CHILDREN | wxSW_3D, + const wxString& name = "layoutWindow"); + + /** + Returns the alignment of the window: one of wxLAYOUT_TOP, wxLAYOUT_LEFT, + wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. + */ + wxLayoutAlignment GetAlignment(); + + /** + Returns the orientation of the window: one of wxLAYOUT_HORIZONTAL, + wxLAYOUT_VERTICAL. + */ + wxLayoutOrientation GetOrientation(); + + /** + The default handler for the event that is generated by wxLayoutAlgorithm. The + implementation + of this function calls wxCalculateLayoutEvent::SetRect to shrink the provided + size according to + how much space this window takes up. For further details, + see wxLayoutAlgorithm and wxCalculateLayoutEvent. + */ + void OnCalculateLayout(wxCalculateLayoutEvent& event); + + /** + The default handler for the event that is generated by OnCalculateLayout to get + size, alignment and orientation information for the window. The implementation + of this function uses member variables as set by accessors called by the + application. + For further details, see wxLayoutAlgorithm and wxQueryLayoutInfoEvent. + */ + void OnQueryLayoutInfo(wxQueryLayoutInfoEvent& event); + + /** + Sets the alignment of the window (which edge of the available parent client + area the window + is attached to). @e alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT, + wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. + */ + void SetAlignment(wxLayoutAlignment alignment); + + /** + Sets the default dimensions of the window. The dimension other than the + orientation will be fixed to this + value, and the orientation dimension will be ignored and the window stretched + to fit the available space. + */ + void SetDefaultSize(const wxSize& size); + + /** + Sets the orientation of the window (the direction the window will stretch in, + to fill the available + parent client area). @e orientation is one of wxLAYOUT_HORIZONTAL, + wxLAYOUT_VERTICAL. + */ + void SetOrientation(wxLayoutOrientation orientation); +}; + + +/** + @class wxQueryLayoutInfoEvent + @wxheader{laywin.h} + + This event is sent when wxLayoutAlgorithm wishes to get + the size, orientation and alignment of a window. More precisely, the event is + sent + by the OnCalculateLayout handler which is itself invoked by wxLayoutAlgorithm. + + @library{wxadv} + @category{events} + + @seealso + wxCalculateLayoutEvent, wxSashLayoutWindow, wxLayoutAlgorithm. +*/ +class wxQueryLayoutInfoEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxQueryLayoutInfoEvent(wxWindowID id = 0); + + /** + Specifies the alignment of the window (which side of the remaining parent + client area + the window sticks to). One of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT, + wxLAYOUT_BOTTOM. + */ + void GetAlignment(); + + /** + Returns the flags associated with this event. Not currently used. + */ + int GetFlags(); + + /** + Returns the orientation that the event handler specified to the event object. + May be one of wxLAYOUT_HORIZONTAL, + wxLAYOUT_VERTICAL. + */ + wxLayoutOrientation GetOrientation(); + + /** + Returns the requested length of the window in the direction of the window + orientation. This information + is not yet used. + */ + int GetRequestedLength(); + + /** + Returns the size that the event handler specified to the event object as being + the requested size of the window. + */ + wxSize GetSize(); + + /** + Call this to specify the alignment of the window (which side of the remaining + parent client area + the window sticks to). May be one of wxLAYOUT_TOP, wxLAYOUT_LEFT, + wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. + */ + void SetAlignment(wxLayoutAlignment alignment); + + /** + Sets the flags associated with this event. Not currently used. + */ + void SetFlags(int flags); + + /** + Call this to specify the orientation of the window. May be one of + wxLAYOUT_HORIZONTAL, + wxLAYOUT_VERTICAL. + */ + void SetOrientation(wxLayoutOrientation orientation); + + /** + Sets the requested length of the window in the direction of the window + orientation. This information + is not yet used. + */ + void SetRequestedLength(int length); + + /** + Call this to let the calling code know what the size of the window is. + */ + void SetSize(const wxSize& size); +}; + + +/** + @class wxCalculateLayoutEvent + @wxheader{laywin.h} + + This event is sent by wxLayoutAlgorithm to + calculate the amount of the remaining client area that the window should + occupy. + + @library{wxadv} + @category{events} + + @seealso + wxQueryLayoutInfoEvent, wxSashLayoutWindow, wxLayoutAlgorithm. +*/ +class wxCalculateLayoutEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxCalculateLayoutEvent(wxWindowID id = 0); + + /** + Returns the flags associated with this event. Not currently used. + */ + int GetFlags(); + + /** + Before the event handler is entered, returns the remaining parent client area + that the window + could occupy. When the event handler returns, this should contain the remaining + parent client rectangle, + after the event handler has subtracted the area that its window occupies. + */ + wxRect GetRect(); + + /** + Sets the flags associated with this event. Not currently used. + */ + void SetFlags(int flags); + + /** + Call this to specify the new remaining parent client area, after the space + occupied by the + window has been subtracted. + */ + void SetRect(const wxRect& rect); +}; diff --git a/interface/link.h b/interface/link.h new file mode 100644 index 0000000000..0714f6c6d2 --- /dev/null +++ b/interface/link.h @@ -0,0 +1,34 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: link.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + This macro can be used in conjunction with the + wxFORCE_LINK_MODULE macro to force + the linker to include in its output a specific object file. + + In particular, you should use this macro in the source file which you want + to force for inclusion. The @c moduleName needs to be a name not already + in use in other @c wxFORCE_LINK_THIS_MODULE macros, but is not required + to be e.g. the same name of the source file (even if it's a good choice). +*/ +#define wxFORCE_LINK_THIS_MODULE() /* implementation is private */ + + + /** + This macro can be used in conjunction with the + wxFORCE_LINK_THIS_MODULE macro to force + the linker to include in its output a specific object file. + + In particular, you should use this macro in a source file which you know + for sure is linked in the output (e.g. the source file containing the "main()" + of your app). The @c moduleName is the name of the module you want to + forcefully link + (i.e. the name you used in the relative wxFORCE_LINK_THIS_MODULE macro. +*/ +#define wxFORCE_LINK_MODULE() /* implementation is private */ + diff --git a/interface/list.h b/interface/list.h new file mode 100644 index 0000000000..cf7c7175cf --- /dev/null +++ b/interface/list.h @@ -0,0 +1,367 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: list.h +// Purpose: documentation for wxList class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxListT + @wxheader{list.h} + + The wxListT class provides linked list functionality. It has been rewritten + to be type safe and to provide the full API of the STL std::list container and + should be used like it. The exception is that wxListT actually stores + pointers and therefore its iterators return pointers and not references + to the actual objets in the list (see example below) and @e value_type + is defined as @e T*. wxListT destroys an object after removing it only + if wxList::DeleteContents has been called. + + wxListT is not a real template and it requires that you declare and define + each wxListT class in your program. This is done with @e WX_DECLARE_LIST + and @e WX_DEFINE_LIST macros (see example). We hope that we'll be able + to provide a proper template class providing both the STL std::list + and the old wxList API in the future. + + Please refer to the STL std::list documentation for further + information on how to use the class. Below we documented both + the supported STL and the legacy API that originated from the + old wxList class and which can still be used alternatively for + the the same class. + + Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1) + then wxListT will actually derive from std::list and just add a legacy + compatibility layer for the old wxList class. + + @library{wxbase} + @category{FIXME} + + @seealso + wxArrayT, wxVectorT +*/ +class wxList +{ +public: + //@{ + /** + Constructors. + */ + wxListT(); + wxListT(size_t count, T * elements[]); + //@} + + /** + Destroys the list, but does not delete the objects stored in the list + unless you called DeleteContents(@true ). + */ + ~wxListT(); + + /** + Appends the pointer to @e object to the list. + */ + wxListT::compatibility_iterator Append(T * object); + + /** + Clears the list, but does not delete the objects stored in the list + unless you called DeleteContents(@true ). + */ + void Clear(); + + /** + If @e destroy is @true, instructs the list to call @e delete + on objects stored in the list whenever they are removed. + The default is @false. + */ + void DeleteContents(bool destroy); + + /** + Deletes the given element refered to by @c iter from the list, + returning @true if successful. + */ + bool DeleteNode(const compatibility_iterator& iter); + + /** + Finds the given @e object and removes it from the list, returning + @true if successful. The application must delete the actual object + separately. + */ + bool DeleteObject(T * object); + + /** + Removes element refered to be @c iter. + */ + void Erase(const compatibility_iterator& iter); + + /** + Returns the iterator refering to @e object or @NULL if none found. + */ + wxListT::compatibility_iterator Find(T * object); + + /** + Returns the number of elements in the list. + */ + size_t GetCount(); + + /** + Returns the first iterator in the list (@NULL if the list is empty). + */ + wxListT::compatibility_iterator GetFirst(); + + /** + Returns the last iterator in the list (@NULL if the list is empty). + */ + wxListT::compatibility_iterator GetLast(); + + /** + Returns the index of @e obj within the list or @c wxNOT_FOUND if + @e obj is not found in the list. + */ + int IndexOf(T* obj); + + //@{ + /** + Inserts the object before the object refered to be @e iter. + */ + wxListT::compatibility_iterator Insert(T * object); + wxListT::compatibility_iterator Insert(size_t position, + T * object); + wxListT::compatibility_iterator Insert(compatibility_iterator iter, + T * object); + //@} + + /** + Returns @true if the list is empty, @false otherwise. + */ + bool IsEmpty(); + + /** + Returns the iterator refering to the object at the given + @c index in the list. + */ + wxListT::compatibility_iterator Item(size_t index); + + /** + @b NB: This function is deprecated, use wxList::Find instead. + */ + wxListT::compatibility_iterator Member(T * object); + + /** + @b NB: This function is deprecated, use @ref wxList::itemfunc Item instead. + + Returns the @e nth node in the list, indexing from zero (@NULL if the list is + empty + or the nth node could not be found). + */ +#define wxListT::compatibility_iterator Nth(int n) /* implementation is private */ + + /** + @b NB: This function is deprecated, use wxList::GetCount instead. + + Returns the number of elements in the list. + */ + int Number(); + + /** + Allows the sorting of arbitrary lists by giving a function to compare + two list elements. We use the system @b qsort function for the actual + sorting process. + */ + void Sort(wxSortCompareFunction compfunc); + + //@{ + /** + ) + */ + void assign(const_iterator first, const const_iterator& last); + void assign(size_type n); + //@} + + //@{ + /** + Returns the last item of the list. + */ + reference back(); + const_reference back(); + //@} + + //@{ + /** + Returns a (const) iterator pointing to the beginning of the list. + */ + iterator begin(); + const_iterator begin(); + //@} + + /** + Removes all items from the list. + */ + void clear(); + + /** + Returns @e @true if the list is empty. + */ + bool empty(); + + //@{ + /** + Returns a (const) iterator pointing at the end of the list. + */ + iterator end(); + const_iterator end(); + //@} + + //@{ + /** + Erases the items from @e first to @e last. + */ + iterator erase(const iterator& it); + iterator erase(const iterator& first, + const iterator& last); + //@} + + //@{ + /** + Returns the first item in the list. + */ + reference front(); + const_reference front(); + //@} + + //@{ + /** + Inserts an item (or several) at the given position. + */ + iterator insert(const iterator& it); + void insert(const iterator& it, size_type n); + void insert(const iterator& it, const_iterator first, + const const_iterator& last); + //@} + + /** + Returns the largest possible size of the list. + */ + size_type max_size(); + + /** + Removes the last item from the list. + */ + void pop_back(); + + /** + Removes the first item from the list. + */ + void pop_front(); + + /** + ) + + Adds an item to end of the list. + */ + void push_back(); + + /** + ) + + Adds an item to the front of the list. + */ + void push_front(); + + //@{ + /** + Returns a (const) reverse iterator pointing to the beginning of the + reversed list. + */ + reverse_iterator rbegin(); + const_reverse_iterator rbegin(); + //@} + + /** + Removes an item from the list. + */ + void remove(const_reference v); + + //@{ + /** + Returns a (const) reverse iterator pointing to the end of the + reversed list. + */ + reverse_iterator rend(); + const_reverse_iterator rend(); + //@} + + /** + ) + + Resizes the list. If the the list is enlarges items with + the value @e v are appended to the list. + */ + void resize(size_type n); + + /** + Reverses the list. + */ + void reverse(); + + /** + Returns the size of the list. + */ + size_type size(); +}; + + +/** + @class wxNode + @wxheader{list.h} + + wxNodeBase is the node structure used in linked lists (see + wxList) and derived classes. You should never use wxNodeBase + class directly, however, because it works with untyped (@c void *) data and + this is unsafe. Use wxNodeBase-derived classes which are automatically defined + by WX_DECLARE_LIST and WX_DEFINE_LIST macros instead as described in + wxList documentation (see example there). Also note that + although there is a class called wxNode, it is defined for backwards + compatibility only and usage of this class is strongly deprecated. + + In the documentation below, the type @c T should be thought of as a + "template'' parameter: this is the type of data stored in the linked list or, + in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is + written as wxNodeT even though it isn't really a template class -- but it + helps to think of it as if it were. + + @library{wxbase} + @category{FIXME} + + @seealso + wxList, wxHashTable +*/ +class wxNode +{ +public: + /** + Retrieves the client data pointer associated with the node. + */ + T * GetData(); + + /** + Retrieves the next node or @NULL if this node is the last one. + */ + wxNodeT * GetNext(); + + /** + Retrieves the previous node or @NULL if this node is the first one in the list. + */ + wxNodeT * GetPrevious(); + + /** + Returns the zero-based index of this node within the list. The return value + will be @c wxNOT_FOUND if the node has not been added to a list yet. + */ + int IndexOf(); + + /** + Sets the data associated with the node (usually the pointer will have been + set when the node was created). + */ + void SetData(T * data); +}; diff --git a/interface/listbook.h b/interface/listbook.h new file mode 100644 index 0000000000..044194e423 --- /dev/null +++ b/interface/listbook.h @@ -0,0 +1,57 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: listbook.h +// Purpose: documentation for wxListbook class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxListbook + @wxheader{listbook.h} + + wxListbook is a class similar to wxNotebook but which + uses a wxListCtrl to show the labels instead of the + tabs. + + There is no documentation for this class yet but its usage is + identical to wxNotebook (except for the features clearly related to tabs + only), so please refer to that class documentation for now. You can also + use the @ref overview_samplenotebook "notebook sample" to see wxListbook in + action. + + @beginStyleTable + @style{wxLB_DEFAULT}: + Choose the default location for the labels depending on the current + platform (left everywhere except Mac where it is top). + @style{wxLB_TOP}: + Place labels above the page area. + @style{wxLB_LEFT}: + Place labels on the left side. + @style{wxLB_RIGHT}: + Place labels on the right side. + @style{wxLB_BOTTOM}: + Place labels below the page area. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @seealso + wxBookCtrl, wxNotebook, @ref overview_samplenotebook "notebook sample" +*/ +class wxListbook : public wxBookCtrl overview +{ +public: + //@{ + /** + Constructs a listbook control. + */ + wxListbook(); + wxListbook(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxEmptyStr); + //@} +}; diff --git a/interface/listbox.h b/interface/listbox.h new file mode 100644 index 0000000000..ca07ba4a0c --- /dev/null +++ b/interface/listbox.h @@ -0,0 +1,250 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: listbox.h +// Purpose: documentation for wxListBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxListBox + @wxheader{listbox.h} + + A listbox is used to select one or more of a list of strings. The + strings are displayed in a scrolling box, with the selected string(s) + marked in reverse video. A listbox can be single selection (if an item + is selected, the previous selection is removed) or multiple selection + (clicking an item toggles the item on or off independently of other + selections). + + List box elements are numbered from zero. Their number may be limited + under some platforms. + + A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for single + clicks, and + wxEVT_COMMAND_LISTBOX_DOUBLE_CLICKED for double clicks. + + @beginStyleTable + @style{wxLB_SINGLE}: + Single-selection list. + @style{wxLB_MULTIPLE}: + Multiple-selection list: the user can toggle multiple items on and + off. + @style{wxLB_EXTENDED}: + Extended-selection list: the user can select multiple items using + the SHIFT key and the mouse or special key combinations. + @style{wxLB_HSCROLL}: + Create horizontal scrollbar if contents are too wide (Windows only). + @style{wxLB_ALWAYS_SB}: + Always show a vertical scrollbar. + @style{wxLB_NEEDED_SB}: + Only create a vertical scrollbar if needed. + @style{wxLB_SORT}: + The listbox contents are sorted in alphabetical order. + @endStyleTable + + @beginEventTable + @event{EVT_LISTBOX(id\, func)}: + Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the + list is selected or the selection changes. + @event{EVT_LISTBOX_DCLICK(id\, func)}: + Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the + listbox is double-clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{listbox.png} + + @seealso + wxChoice, wxComboBox, wxListCtrl, wxCommandEvent +*/ +class wxListBox : public wxControlWithItems +{ +public: + //@{ + /** + Constructor, creating and showing a list box. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param n + Number of strings with which to initialise the control. + + @param choices + An array of strings with which to initialise the control. + + @param style + Window style. See wxListBox. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxListBox(); + wxListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = @NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + wxListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + //@} + + /** + Destructor, destroying the list box. + */ + ~wxListBox(); + + //@{ + /** + Creates the listbox for two-step construction. See wxListBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, + const wxString choices[] = @NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + //@} + + /** + Deselects an item in the list box. + + @param n + The zero-based item to deselect. + + @remarks This applies to multiple selection listboxes only. + */ + void Deselect(int n); + + /** + Fill an array of ints with the positions of the currently selected items. + + @param selections + A reference to an wxArrayInt instance that is used to store the result of the + query. + + @returns The number of selections. + + @remarks Use this with a multiple selection listbox. + + @sa wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection, + wxControlWithItems::SetSelection + */ + int GetSelections(wxArrayInt& selections); + + /** + Returns the item located at @e point, or @c wxNOT_FOUND if there + is no item located at @e point. + + This function is new since wxWidgets version 2.7.0. It is currently implemented + for wxMSW, wxMac and wxGTK2 + ports. + + @param point + Point of item (in client coordinates) to obtain + + @returns Item located at point, or wxNOT_FOUND if unimplemented or the + item does not exist. + */ + int HitTest(const wxPoint point); + + //@{ + /** + Insert the given number of strings before the specified position. + + @param nItems + Number of items in the array items + + @param items + Labels of items to be inserted + + @param pos + Position before which to insert the items: for example, if pos is 0 the items + will be inserted in the beginning of the listbox + */ + void InsertItems(int nItems, const wxString items, + unsigned int pos); + void InsertItems(const wxArrayString& nItems, + unsigned int pos); + //@} + + /** + Determines whether an item is selected. + + @param n + The zero-based item index. + + @returns @true if the given item is selected, @false otherwise. + */ + bool IsSelected(int n); + + //@{ + /** + Clears the list box and adds the given strings to it. + + @param n + The number of strings to set. + + @param choices + An array of strings to set. + + @param clientData + Options array of client data pointers + + @remarks You may free the array from the calling program after this + function has been called. + */ + void Set(int n, const wxString* choices, void clientData = @NULL); + void Set(const wxArrayString& choices, + void clientData = @NULL); + //@} + + //@{ + /** + Set the specified item to be the first visible item. + + @param n + The zero-based item index. + + @param string + The string that should be visible. + */ + void SetFirstItem(int n); + void SetFirstItem(const wxString& string); + //@} +}; diff --git a/interface/listctrl.h b/interface/listctrl.h new file mode 100644 index 0000000000..c8b0601d9e --- /dev/null +++ b/interface/listctrl.h @@ -0,0 +1,1496 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: listctrl.h +// Purpose: documentation for wxListCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxListCtrl + @wxheader{listctrl.h} + + A list control presents lists in a number of formats: list view, report view, + icon view and small icon view. In any case, elements are numbered from zero. + For all these modes, the items are stored in the control and must be added to + it using wxListCtrl::InsertItem method. + + A special case of report view quite different from the other modes of the list + control is a virtual control in which the items data (including text, images + and attributes) is managed by the main program and is requested by the control + itself only when needed which allows to have controls with millions of items + without consuming much memory. To use virtual list control you must use + wxListCtrl::SetItemCount first and overload at least + wxListCtrl::OnGetItemText (and optionally + wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and + wxListCtrl::OnGetItemAttr) to return the information + about the items when the control requests it. Virtual list control can be used + as a normal one except that no operations which can take time proportional to + the number of items in the control happen -- this is required to allow having a + practically infinite number of items. For example, in a multiple selection + virtual list control, the selections won't be sent when many items are selected + at once because this could mean iterating over all the items. + + Using many of wxListCtrl features is shown in the + @ref overview_samplelistctrl "corresponding sample". + + To intercept events from a list control, use the event table macros described + in wxListEvent. + + @b Mac Note: Starting with 2.8, wxListCtrl uses a native implementation for + report mode, and uses a generic implementation for other modes. You can use the + generic implementation for report mode as well by setting the + mac.listctrl.always_use_generic wxSystemOption to + 1. + + @beginStyleTable + @style{wxLC_LIST}: + Multicolumn list view, with optional small icons. Columns are + computed automatically, i.e. you don't set columns as in + wxLC_REPORT. In other words, the list wraps, unlike a wxListBox. + @style{wxLC_REPORT}: + Single or multicolumn report view, with optional header. + @style{wxLC_VIRTUAL}: + The application provides items text on demand. May only be used + with wxLC_REPORT. + @style{wxLC_ICON}: + Large icon view, with optional labels. + @style{wxLC_SMALL_ICON}: + Small icon view, with optional labels. + @style{wxLC_ALIGN_TOP}: + Icons align to the top. Win32 default, Win32 only. + @style{wxLC_ALIGN_LEFT}: + Icons align to the left. + @style{wxLC_AUTOARRANGE}: + Icons arrange themselves. Win32 only. + @style{wxLC_EDIT_LABELS}: + Labels are editable: the application will be notified when editing + starts. + @style{wxLC_NO_HEADER}: + No header in report mode. + @style{wxLC_SINGLE_SEL}: + Single selection (default is multiple). + @style{wxLC_SORT_ASCENDING}: + Sort in ascending order (must still supply a comparison callback in + SortItems. + @style{wxLC_SORT_DESCENDING}: + Sort in descending order (must still supply a comparison callback + in SortItems. + @style{wxLC_HRULES}: + Draws light horizontal rules between rows in report mode. + @style{wxLC_VRULES}: + Draws light vertical rules between columns in report mode. + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{listctrl.png} + + @seealso + @ref overview_wxlistctrloverview "wxListCtrl overview", wxListView, wxListBox, + wxTreeCtrl, wxImageList, wxListEvent, wxListItem +*/ +class wxListCtrl : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a list control. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param style + Window style. See wxListCtrl. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxListCtrl(); + wxListCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxLC_ICON, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxListCtrlNameStr); + //@} + + /** + Destructor, destroying the list control. + */ + ~wxListCtrl(); + + /** + Arranges the items in icon or small icon view. This only has effect on Win32. + @e flag is one of: + + + wxLIST_ALIGN_DEFAULT + + + Default alignment. + + wxLIST_ALIGN_LEFT + + + Align to the left side of the control. + + wxLIST_ALIGN_TOP + + + Align to the top side of the control. + + wxLIST_ALIGN_SNAP_TO_GRID + + + Snap to grid. + */ + bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); + + /** + Sets the image list associated with the control and + takes ownership of it (i.e. the control will, unlike when using + SetImageList, delete the list when destroyed). @e which is one of + wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is + unimplemented). + + @sa SetImageList() + */ + void AssignImageList(wxImageList* imageList, int which); + + /** + Deletes all items and all columns. + */ + void ClearAll(); + + /** + Creates the list control. See wxListCtrl() for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxLC_ICON, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxListCtrlNameStr); + + /** + Deletes all items in the list control. + + @b NB: This function does @e not send the + @c wxEVT_COMMAND_LIST_DELETE_ITEM event because deleting many items + from the control would be too slow then (unlike wxListCtrl::DeleteItem). + */ + bool DeleteAllItems(); + + /** + Deletes a column. + */ + bool DeleteColumn(int col); + + /** + Deletes the specified item. This function sends the + @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the item being deleted. + + See also: DeleteAllItems() + */ + bool DeleteItem(long item); + + /** + Starts editing the label of the given item. This function generates a + EVT_LIST_BEGIN_LABEL_EDIT event which can be vetoed so that no + text control will appear for in-place editing. + + If the user changed the label (i.e. s/he does not press ESC or leave + the text control without changes, a EVT_LIST_END_LABEL_EDIT event + will be sent which can be vetoed as well. + */ + void EditLabel(long item); + + /** + Ensures this item is visible. + */ + bool EnsureVisible(long item); + + //@{ + /** + Find an item nearest this position in the specified direction, starting from + @e start or the beginning if @e start is -1. + + + + @b FindItem( start, str, partial = @false ) + + + + @b FindItemData( start, data ) + + + + @b FindItemAtPos( start, point, direction ) + */ + long FindItem(long start, const wxString& str, + bool partial = @false); + long FindItem(long start, long data); + long FindItem(long start, const wxPoint& pt, int direction); + //@} + + /** + Gets information about this column. See SetItem() for more + information. + */ + bool GetColumn(int col, wxListItem& item); + + /** + Returns the number of columns. + */ + int GetColumnCount(); + + /** + Gets the column number by visual order index (report view only). + */ + int GetColumnIndexFromOrder(int order); + + /** + Gets the column visual order index (valid in report view only). + */ + int GetColumnOrder(int col); + + /** + Gets the column width (report view only). + */ + int GetColumnWidth(int col); + + /** + Returns the array containing the orders of all columns. On error, an empty + array is returned. + */ + wxArrayInt GetColumnsOrder(); + + /** + Gets the number of items that can fit vertically in the + visible area of the list control (list or report view) + or the total number of items in the list control (icon + or small icon view). + */ + int GetCountPerPage(); + + /** + Returns the edit control being currently used to edit a label. Returns @NULL + if no label is being edited. + + @b NB: It is currently only implemented for wxMSW and the generic version, + not for the native Mac OS X version. + */ + wxTextCtrl * GetEditControl(); + + /** + Returns the specified image list. @e which may be one of: + + + @b wxIMAGE_LIST_NORMAL + + + The normal (large icon) image list. + + @b wxIMAGE_LIST_SMALL + + + The small icon image list. + + @b wxIMAGE_LIST_STATE + + + The user-defined state image list (unimplemented). + */ + wxImageList* GetImageList(int which); + + /** + Gets information about the item. See SetItem() for more + information. + + You must call @e info.SetId() to the ID of item you're interested in + before calling this method. + */ + bool GetItem(wxListItem& info); + + /** + Returns the colour for this item. If the item has no specific colour, returns + an invalid colour (and not the default background control of the control + itself). + + @sa GetItemTextColour() + */ + wxColour GetItemBackgroundColour(long item); + + /** + Returns the number of items in the list control. + */ + int GetItemCount(); + + /** + Gets the application-defined data associated with this item. + */ + long GetItemData(long item); + + /** + Returns the item's font. + */ + wxFont GetItemFont(long item); + + /** + Returns the position of the item, in icon or small icon view. + */ + bool GetItemPosition(long item, wxPoint& pos); + + /** + Returns the rectangle representing the item's size and position, in physical + coordinates. + + @e code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL. + */ + bool GetItemRect(long item, wxRect& rect, + int code = wxLIST_RECT_BOUNDS); + + /** + Retrieves the spacing between icons in pixels: horizontal spacing is returned + as @c x component of the wxSize object and the vertical + spacing as its @c y component. + */ + wxSize GetItemSpacing(); + + /** + Gets the item state. For a list of state flags, see SetItem(). + + The @b stateMask indicates which state flags are of interest. + */ + int GetItemState(long item, long stateMask); + + /** + Gets the item text for this item. + */ + wxString GetItemText(long item); + + /** + Returns the colour for this item. If the item has no specific colour, returns + an invalid colour (and not the default foreground control of the control itself + as this wouldn't allow distinguishing between items having the same colour as + the current control foreground and items with default colour which, hence, have + always the same colour as the control). + */ + wxColour GetItemTextColour(long item); + + /** + Searches for an item with the given geometry or state, starting from + @e item but excluding the @e item itself. If @e item is -1, + the first item that matches the specified flags will be returned. + + Returns the first item with given state following @e item or -1 if + no such item found. + + This function may be used to find all selected items in the control like this: + @e geometry can be one of: + + + wxLIST_NEXT_ABOVE + + + Searches for an item above the specified item. + + wxLIST_NEXT_ALL + + + Searches for subsequent item by index. + + wxLIST_NEXT_BELOW + + + Searches for an item below the specified item. + + wxLIST_NEXT_LEFT + + + Searches for an item to the left of the specified item. + + wxLIST_NEXT_RIGHT + + + Searches for an item to the right of the specified item. + + @b NB: this parameter is only supported by wxMSW currently and ignored on + other platforms. + + @e state can be a bitlist of the following: + + + wxLIST_STATE_DONTCARE + + + Don't care what the state is. + + wxLIST_STATE_DROPHILITED + + + The item indicates it is a drop target. + + wxLIST_STATE_FOCUSED + + + The item has the focus. + + wxLIST_STATE_SELECTED + + + The item is selected. + + wxLIST_STATE_CUT + + + The item is selected as part of a cut and paste operation. + */ + long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, + int state = wxLIST_STATE_DONTCARE); + + /** + Returns the number of selected items in the list control. + */ + int GetSelectedItemCount(); + + /** + Returns the rectangle representing the size and position, in physical + coordinates, of the given subitem, i.e. the part of the row @e item in the + column @e subItem. + + This method is only meaningfull when the wxListCtrl is in the report mode. If + @e subItem parameter is equal to the special value + @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as + for GetItemRect(). + + @e code can be one of @c wxLIST_RECT_BOUNDS, + @c wxLIST_RECT_ICON or @c wxLIST_RECT_LABEL. + + This function is new since wxWidgets version 2.7.0 + */ + bool GetSubItemRect(long item, long subItem, wxRect& rect, + int code = wxLIST_RECT_BOUNDS); + + /** + Gets the text colour of the list control. + */ + wxColour GetTextColour(); + + /** + Gets the index of the topmost visible item when in + list or report view. + */ + long GetTopItem(); + + /** + Returns the rectangle taken by all items in the control. In other words, if the + controls client size were equal to the size of this rectangle, no scrollbars + would be needed and no free space would be left. + + Note that this function only works in the icon and small icon views, not in + list or report views (this is a limitation of the native Win32 control). + */ + wxRect GetViewRect(); + + /** + Determines which item (if any) is at the specified point, + giving details in @e flags. Returns index of the item or @c wxNOT_FOUND + if no item is at the specified point. + @e flags will be a combination of the following flags: + + + wxLIST_HITTEST_ABOVE + + + Above the client area. + + wxLIST_HITTEST_BELOW + + + Below the client area. + + wxLIST_HITTEST_NOWHERE + + + In the client area but below the last item. + + wxLIST_HITTEST_ONITEMICON + + + On the bitmap associated with an item. + + wxLIST_HITTEST_ONITEMLABEL + + + On the label (string) associated with an item. + + wxLIST_HITTEST_ONITEMRIGHT + + + In the area to the right of an item. + + wxLIST_HITTEST_ONITEMSTATEICON + + + On the state icon for a tree view item that is in a user-defined state. + + wxLIST_HITTEST_TOLEFT + + + To the right of the client area. + + wxLIST_HITTEST_TORIGHT + + + To the left of the client area. + + wxLIST_HITTEST_ONITEM + + + Combination of wxLIST_HITTEST_ONITEMICON, wxLIST_HITTEST_ONITEMLABEL, + wxLIST_HITTEST_ONITEMSTATEICON. + + If @e ptrSubItem is not @NULL and the wxListCtrl is in the report + mode the subitem (or column) number will also be provided. + This feature is only available in version 2.7.0 or higher and is currently only + implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on + the host system or the value stored in @e ptrSubItem will be always -1. To + compile this feature into wxWidgets library you need to have access to + commctrl.h of version 4.70 that is provided by Microsoft. + */ + long HitTest(const wxPoint& point, int& flags, + long * ptrSubItem); + + //@{ + /** + For report view mode (only), inserts a column. For more details, see SetItem(). + */ + long InsertColumn(long col, wxListItem& info); + long InsertColumn(long col, const wxString& heading, + int format = wxLIST_FORMAT_LEFT, + int width = -1); + //@} + + //@{ + /** + Insert an image/string item. + + @param info + wxListItem object + + @param index + Index of the new item, supplied by the application + + @param label + String label + + @param imageIndex + index into the image list associated with this control and view style + */ + long InsertItem(wxListItem& info); + long InsertItem(long index, const wxString& label); + long InsertItem(long index, int imageIndex); + long InsertItem(long index, const wxString& label, + int imageIndex); + //@} + + /** + This function may be overloaded in the derived class for a control with + @c wxLC_VIRTUAL style. It should return the attribute for the + for the specified @c item or @NULL to use the default appearance + parameters. + + wxListCtrl will not delete the pointer or keep a reference of it. You can + return the same wxListItemAttr pointer for every OnGetItemAttr call. + + The base class version always returns @NULL. + + @sa OnGetItemImage(), OnGetItemColumnImage(), + OnGetItemText() + */ + virtual wxListItemAttr * OnGetItemAttr(long item); + + /** + Overload this function in the derived class for a control with + @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image + index for the given line and column. + + The base class version always calls OnGetItemImage for the first column, else + it returns -1. + + @sa OnGetItemText(), OnGetItemImage(), + OnGetItemAttr() + */ + virtual int OnGetItemColumnImage(long item, long column); + + /** + This function must be overloaded in the derived class for a control with + @c wxLC_VIRTUAL style having an @ref setimagelist() "image list" + (if the control doesn't have an image list, it is not necessary to overload + it). It should return the index of the items image in the controls image list + or -1 for no image. + In a control with @c wxLC_REPORT style, OnGetItemImage only gets called for + the first column of each line. + + The base class version always returns -1. + + @sa OnGetItemText(), OnGetItemColumnImage(), + OnGetItemAttr() + */ + virtual int OnGetItemImage(long item); + + /** + This function @b must be overloaded in the derived class for a control with + @c wxLC_VIRTUAL style. It should return the string containing the text of + the given @e column for the specified @c item. + + @sa SetItemCount(), OnGetItemImage(), + OnGetItemColumnImage(), OnGetItemAttr() + */ + virtual wxString OnGetItemText(long item, long column); + + /** + Redraws the given @e item. This is only useful for the virtual list controls + as without calling this function the displayed value of the item doesn't change + even when the underlying data does change. + + @sa RefreshItems() + */ + void RefreshItem(long item); + + /** + Redraws the items between @e itemFrom and @e itemTo. The starting item + must be less than or equal to the ending one. + + Just as RefreshItem() this is only useful for + virtual list controls. + */ + void RefreshItems(long itemFrom, long itemTo); + + /** + Scrolls the list control. If in icon, small icon or report view mode, + @e dx specifies the number of pixels to scroll. If in list view mode, + @e dx specifies the number of columns to scroll. @e dy always specifies + the number of pixels to scroll vertically. + + @b NB: This method is currently only implemented in the Windows version. + */ + bool ScrollList(int dx, int dy); + + /** + Sets the background colour (GetBackgroundColour already implicit in + wxWindow class). + */ + void SetBackgroundColour(const wxColour& col); + + /** + Sets information about this column. See SetItem() for more + information. + */ + bool SetColumn(int col, wxListItem& item); + + /** + Sets the column width. + + @e width can be a width in pixels or wxLIST_AUTOSIZE (-1) or + wxLIST_AUTOSIZE_USEHEADER (-2). + wxLIST_AUTOSIZE will resize the column to the length of its longest item. + wxLIST_AUTOSIZE_USEHEADER + will resize the column to the length of the header (Win32) or 80 pixels (other + platforms). + + In small or normal icon view, @e col must be -1, and the column width is set + for all columns. + */ + bool SetColumnWidth(int col, int width); + + /** + Sets the order of all columns at once. The @e orders array must have the + same number elements as the number of columns and contain each position exactly + once. + + This function is valid in report view only. + */ + bool SetColumnOrder(const wxArrayInt& orders); + + /** + Sets the image list associated with the control. @e which is one of + wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is + unimplemented). + + This method does not take ownership of the image list, you have to + delete it yourself. + + @sa AssignImageList() + */ + void SetImageList(wxImageList* imageList, int which); + + //@{ + /** + Sets a string field at a particular column. + */ + bool SetItem(wxListItem& info); + long SetItem(long index, int col, const wxStringamp; label, + int imageId = -1); + m_mask m_state field is valid. + + + + + +wxLIST_MASK_TEXT + + + + +The m_text field is valid. + + + + + +wxLIST_MASK_IMAGE + + + + +The m_image field is valid. + + + + + +wxLIST_MASK_DATA + + + + +The m_data field is valid. + + + + + +wxLIST_MASK_WIDTH + + + + +The m_width field is valid. + + + + + +wxLIST_MASK_FORMAT + + + + +The m_format field is valid. + + + + + +The m_stateMask and m_state members take flags from the following: + + + + + + + +wxLIST_STATE_DONTCARE + + + + +Don't care what the state is. Win32 only. + + + + + +wxLIST_STATE_DROPHILITED + + + + +The item is highlighted to receive a drop event. Win32 only. + + + + + +wxLIST_STATE_FOCUSED + + + + +The item has the focus. + + + + + +wxLIST_STATE_SELECTED + + + + +The item is selected. + + + + + +wxLIST_STATE_CUT + + + + +The item is in the cut state. Win32 only. + + + + + +The wxListItem object can also contain item-specific colour and font +information: for this you need to call one of SetTextColour(), +SetBackgroundColour() or SetFont() functions on it passing it the colour/font +to use. If the colour/font is not specified, the default list control +colour/font is used. +long SetItem(long index, int col, const wxString& label, + int imageId = -1); + //@} + + /** + Sets the background colour for this item. This function only works in report + view. + + The colour can be retrieved using + GetItemBackgroundColour(). + */ + void SetItemBackgroundColour(long item, const wxColour& col); + + /** + Sets the image associated with the item. In report view, you can specify the + column. + The image is an index into the image list associated with the list control. + */ + bool SetItemColumnImage(long item, long column, int image); + + /** + This method can only be used with virtual list controls. It is used to indicate + to the control the number of items it contains. After calling it, the main + program should be ready to handle calls to various item callbacks (such as + wxListCtrl::OnGetItemText) for all items in the range + from 0 to @e count. + */ + void SetItemCount(long count); + + /** + Associates application-defined data with this item. + + Notice that this function cannot be used to associate pointers with the control + items, use SetItemPtrData() instead. + */ + bool SetItemData(long item, long data); + + /** + Sets the item's font. + */ + void SetItemFont(long item, const wxFont& font); + + //@{ + /** + Sets the unselected and selected images associated with the item. The images + are indices into the + image list associated with the list control. This form is deprecated: @e + selImage is not + used. + */ + bool SetItemImage(long item, int image); + bool SetItemImage(long item, int image, int selImage); + //@} + + /** + Sets the position of the item, in icon or small icon view. Windows only. + */ + bool SetItemPosition(long item, const wxPoint& pos); + + /** + Associates application-defined data with this item. The @e data parameter may + be either an integer or a pointer cast to the @c wxUIntPtr type which is + guaranteed to be large enough to be able to contain all integer types and + pointers. + + This function is new since wxWidgets version 2.8.4 + */ + bool SetItemPtrData(long item, wxUIntPtr data); + + /** + Sets the item state. For a list of state flags, see SetItem(). + + The @b stateMask indicates which state flags are valid. + */ + bool SetItemState(long item, long state, long stateMask); + + /** + Sets the item text for this item. + */ + void SetItemText(long item, const wxString& text); + + /** + Sets the colour for this item. This function only works in report view. + + The colour can be retrieved using + GetItemTextColour(). + */ + void SetItemTextColour(long item, const wxColour& col); + + /** + Adds or removes a single window style. + */ + void SetSingleStyle(long style, bool add = @true); + + /** + Sets the text colour of the list control. + */ + void SetTextColour(const wxColour& col); + + /** + Sets the whole window style, deleting all items. + */ + void SetWindowStyleFlag(long style); + + /** + Call this function to sort the items in the list control. Sorting is done + using the specified @e fnSortCallBack function. This function must have the + following prototype: + It is called each time when the two items must be compared and should return 0 + if the items are equal, negative value if the first item is less than the + second one and positive value if the first one is greater than the second one + (the same convention as used by @c qsort(3)). + + @param item1 + client data associated with the first item (NOT the index). + + @param item2 + client data associated with the second item (NOT the index). + + @param data + the value passed to SortItems() itself. + */ + bool SortItems(wxListCtrlCompare fnSortCallBack, long data); +}; + + +/** + @class wxListEvent + @wxheader{listctrl.h} + + A list event holds information about events associated with wxListCtrl objects. + + @library{wxbase} + @category{events} + + @seealso + wxListCtrl +*/ +class wxListEvent : public wxNotifyEvent +{ +public: + /** + Constructor. + */ + wxListEvent(WXTYPE commandType = 0, int id = 0); + + /** + For @c EVT_LIST_CACHE_HINT event only: return the first item which the + list control advises us to cache. + */ + long GetCacheFrom(); + + /** + For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive) + which the list control advises us to cache. + */ + long GetCacheTo(); + + /** + The column position: it is only used with @c COL events. For the column + dragging events, it is the column to the left of the divider being dragged, for + the column click events it may be -1 if the user clicked in the list control + header outside any column. + */ + int GetColumn(); + + /** + The data. + */ + long GetData(); + + /** + The image. + */ + int GetImage(); + + /** + The item index. + */ + long GetIndex(); + + /** + An item object, used by some events. See also wxListCtrl::SetItem. + */ + const wxListItem GetItem(); + + /** + Key code if the event is a keypress event. + */ + int GetKeyCode(); + + /** + The (new) item label for @c EVT_LIST_END_LABEL_EDIT event. + */ + const wxString GetLabel(); + + /** + The mask. + */ + long GetMask(); + + /** + The position of the mouse pointer if the event is a drag event. + */ + wxPoint GetPoint(); + + /** + The text. + */ + const wxString GetText(); + + /** + This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message + and returns @true if it the label editing has been cancelled by the user + (GetLabel() returns an empty string in this case + but it doesn't allow the application to distinguish between really cancelling + the edit and + the admittedly rare case when the user wants to rename it to an empty string). + */ + bool IsEditCancelled(); +}; + + +/** + @class wxListItemAttr + @wxheader{listctrl.h} + + Represents the attributes (color, font, ...) of a + wxListCtrl wxListItem. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxlistctrloverview "wxListCtrl overview", wxListCtrl, wxListItem +*/ +class wxListItemAttr +{ +public: + //@{ + /** + Construct a wxListItemAttr with the specified foreground and + background colors and font. + */ + wxListItemAttr(); + wxListItemAttr(const wxColour colText, + const wxColour colBack, + const wxFont font); + //@} + + /** + Returns the currently set background color. + */ + const wxColour GetBackgroundColour(); + + /** + Returns the currently set font. + */ + const wxFont GetFont(); + + /** + Returns the currently set text color. + */ + const wxColour GetTextColour(); + + /** + Returns @true if the currently set background color is valid. + */ + bool HasBackgroundColour(); + + /** + Returns @true if the currently set font is valid. + */ + bool HasFont(); + + /** + Returns @true if the currently set text color is valid. + */ + bool HasTextColour(); + + /** + Sets a new background color. + */ + void SetBackgroundColour(const wxColour& colour); + + /** + Sets a new font. + */ + void SetFont(const wxFont& font); + + /** + Sets a new text color. + */ + void SetTextColour(const wxColour& colour); +}; + + +/** + @class wxListView + @wxheader{listctrl.h} + + This class currently simply presents a simpler to use interface for the + wxListCtrl -- it can be thought of as a @e faade + for that complicated class. Using it is preferable to using + wxListCtrl directly whenever possible because in the + future some ports might implement wxListView but not the full set of wxListCtrl + features. + + Other than different interface, this class is identical to wxListCtrl. In + particular, it uses the same events, same window styles and so on. + + @library{wxcore} + @category{ctrl} + @appearance{listview.png} + + @seealso + wxListView::SetColumnImage +*/ +class wxListView : public wxListCtrl +{ +public: + /** + Resets the column image -- after calling this function, no image will be shown. + + @param col + the column to clear image for + + @sa SetColumnImage() + */ + void ClearColumnImage(int col); + + /** + Sets focus to the item with the given @e index. + */ + void Focus(long index); + + /** + Returns the first selected item in a (presumably) multiple selection control. + Together with GetNextSelected() it can be + used to iterate over all selected items in the control. + + @returns The first selected item, if any, -1 otherwise. + */ + long GetFirstSelected(); + + /** + Returns the currently focused item or -1 if none. + + @sa IsSelected(), Focus() + */ + long GetFocusedItem(); + + /** + Used together with GetFirstSelected() to + iterate over all selected items in the control. + + @returns Returns the next selected item or -1 if there are no more of + them. + */ + long GetNextSelected(long item); + + /** + Returns @true if the item with the given @e index is selected, + @false otherwise. + + @sa GetFirstSelected(), GetNextSelected() + */ + bool IsSelected(long index); + + /** + Selects or unselects the given item. + + @param n + the item to select or unselect + + @param on + if @true (default), selects the item, otherwise unselects it + + @sa wxListCtrl::SetItemState + */ + void Select(bool on = @true); + + /** + Sets the column image for the specified column. To use the column images, the + control must have a valid image list with at least one image. + + @param col + the column to set image for + + @param image + the index of the column image in the controls image list + */ + void SetColumnImage(int col, int image); +}; + + +/** + @class wxListItem + @wxheader{listctrl.h} + + This class stores information about a wxListCtrl item or column. + + @library{wxbase} + @category{FIXME} +*/ +class wxListItem : public wxObject +{ +public: + /** + Constructor. + */ + wxListItem(); + + /** + Resets the item state to the default. + */ + void Clear(); + + /** + Returns the alignment for this item. Can be one of + wxLIST_FORMAT_LEFT, wxLIST_FORMAT_RIGHT or wxLIST_FORMAT_CENTRE. + */ + wxListColumnFormat GetAlign(); + + /** + Returns the background colour for this item. + */ + wxColour GetBackgroundColour(); + + /** + Returns the zero-based column; meaningful only in report mode. + */ + int GetColumn(); + + /** + Returns client data associated with the control. Please note that + client data is associated with the item and not with subitems. + */ + long GetData(); + + /** + Returns the font used to display the item. + */ + wxFont GetFont(); + + /** + Returns the zero-based item position. + */ + long GetId(); + + /** + Returns the zero-based index of the image + associated with the item into the image list. + */ + int GetImage(); + + /** + Returns a bit mask indicating which fields of the structure are valid; + can be any combination of the following values: + + + wxLIST_MASK_STATE + + + @b GetState is valid. + + wxLIST_MASK_TEXT + + + @b GetText is valid. + + wxLIST_MASK_IMAGE + + + @b GetImage is valid. + + wxLIST_MASK_DATA + + + @b GetData is valid. + + wxLIST_MASK_WIDTH + + + @b GetWidth is valid. + + wxLIST_MASK_FORMAT + + + @b GetFormat is valid. + */ + long GetMask(); + + /** + Returns a bit field representing the state of the item. Can be any + combination of: + + + wxLIST_STATE_DONTCARE + + + Don't care what the state is. Win32 only. + + wxLIST_STATE_DROPHILITED + + + The item is highlighted to receive a drop event. Win32 only. + + wxLIST_STATE_FOCUSED + + + The item has the focus. + + wxLIST_STATE_SELECTED + + + The item is selected. + + wxLIST_STATE_CUT + + + The item is in the cut state. Win32 only. + */ + long GetState(); + + /** + Returns the label/header text. + */ + const wxString GetText(); + + /** + Returns the text colour. + */ + wxColour GetTextColour(); + + /** + Meaningful only for column headers in report mode. Returns the column width. + */ + int GetWidth(); + + /** + Sets the alignment for the item. See also + GetAlign() + */ + void SetAlign(wxListColumnFormat align); + + /** + Sets the background colour for the item. + */ + void SetBackgroundColour(const wxColour& colBack); + + /** + Sets the zero-based column. Meaningful only in report mode. + */ + void SetColumn(int col); + + //@{ + /** + Sets client data for the item. Please note that + client data is associated with the item and not with subitems. + */ + void SetData(long data); + void SetData(void* data); + //@} + + /** + Sets the font for the item. + */ + void SetFont(const wxFont& font); + + /** + Sets the zero-based item position. + */ + void SetId(long id); + + /** + Sets the zero-based index of the image associated with the item + into the image list. + */ + void SetImage(int image); + + /** + Sets the mask of valid fields. See GetMask(). + */ + void SetMask(long mask); + + /** + Sets the item state flags (note that the valid state flags are influenced + by the value of the state mask, see + wxListItem::SetStateMask). + See GetState() for valid flag + values. + */ + void SetState(long state); + + /** + Sets the bitmask that is used to determine which of the state flags + are to be set. See also SetState(). + */ + void SetStateMask(long stateMask); + + /** + Sets the text label for the item. + */ + void SetText(const wxString& text); + + /** + Sets the text colour for the item. + */ + void SetTextColour(const wxColour& colText); + + /** + Meaningful only for column headers in report mode. Sets the column width. + */ + void SetWidth(int width); +}; diff --git a/interface/log.h b/interface/log.h new file mode 100644 index 0000000000..183be4c5b5 --- /dev/null +++ b/interface/log.h @@ -0,0 +1,793 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: log.h +// Purpose: documentation for wxLogWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxLogWindow + @wxheader{log.h} + + This class represents a background log window: to be precise, it collects all + log messages in the log frame which it manages but also passes them on to the + log target which was active at the moment of its creation. This allows, for + example, to show all the log messages in a frame but still continue to process + them normally by showing the standard log dialog. + + @library{wxbase} + @category{logging} + + @seealso + wxLogTextCtrl +*/ +class wxLogWindow : public wxLogInterposer +{ +public: + /** + Creates the log frame window and starts collecting the messages in it. + + @param parent + The parent window for the log frame, may be @NULL + + @param title + The title for the log frame + + @param show + @true to show the frame initially (default), otherwise + Show() must be called later. + + @param passToOld + @true to process the log messages normally in addition to + logging them in the log frame (default), @false to only log them in the + log frame. + */ + wxLogWindow(wxFrame parent, const wxChar title, bool show = @true, + bool passToOld = @true); + + /** + Returns the associated log frame window. This may be used to position or resize + it but use Show() to show or hide it. + */ + wxFrame * GetFrame(); + + /** + Called if the user closes the window interactively, will not be + called if it is destroyed for another reason (such as when program + exits). + + Return @true from here to allow the frame to close, @false to + prevent this from happening. + + @sa OnFrameDelete() + */ + virtual bool OnFrameClose(wxFrame frame); + + /** + Called immediately after the log frame creation allowing for + any extra initializations. + */ + virtual void OnFrameCreate(wxFrame frame); + + /** + Called right before the log frame is going to be deleted: will + always be called unlike OnFrameClose(). + */ + virtual void OnFrameDelete(wxFrame frame); + + /** + Shows or hides the frame. + */ + void Show(bool show = @true); +}; + + +/** + @class wxLogInterposerTemp + @wxheader{log.h} + + A special version of wxLogChain which uses itself as the + new log target. It forwards log messages to the previously installed one in + addition to + processing them itself. Unlike wxLogInterposer, it doesn't + delete the old target which means it can be used to temporarily redirect log + output. + + As per wxLogInterposer, this class must be derived from to implement + wxLog::DoLog + and/or wxLog::DoLogString methods. + + @library{wxbase} + @category{logging} +*/ +class wxLogInterposerTemp : public wxLogChain +{ +public: + /** + The default constructor installs this object as the current active log target. + */ +}; + + +/** + @class wxLogChain + @wxheader{log.h} + + This simple class allows to chain log sinks, that is to install a new sink but + keep passing log messages to the old one instead of replacing it completely as + wxLog::SetActiveTarget does. + + It is especially useful when you want to divert the logs somewhere (for + example to a file or a log window) but also keep showing the error messages + using the standard dialogs as wxLogGui does by default. + + Example of usage: + + @code + wxLogChain *logChain = new wxLogChain(new wxLogStderr); + + // all the log messages are sent to stderr and also processed as usually + ... + + // don't delete logChain directly as this would leave a dangling + // pointer as active log target, use SetActiveTarget() instead + delete wxLog::SetActiveTarget(...something else or @NULL...); + @endcode + + @library{wxbase} + @category{logging} +*/ +class wxLogChain : public wxLog +{ +public: + /** + Sets the specified @c logger (which may be @NULL) as the default log + target but the log messages are also passed to the previous log target if any. + */ + wxLogChain(wxLog * logger); + + /** + Destroys the previous log target. + */ + ~wxLogChain(); + + /** + Detaches the old log target so it won't be destroyed when the wxLogChain object + is destroyed. + */ + void DetachOldLog(); + + /** + Returns the pointer to the previously active log target (which may be @NULL). + */ + wxLog * GetOldLog(); + + /** + Returns @true if the messages are passed to the previously active log + target (default) or @false if PassMessages() + had been called. + */ + bool IsPassingMessages(); + + /** + By default, the log messages are passed to the previously active log target. + Calling this function with @false parameter disables this behaviour + (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and + it can be reenabled by calling it again with @e passMessages set to @true. + */ + void PassMessages(bool passMessages); + + /** + Sets another log target to use (may be @NULL). The log target specified + in the @ref ctor() constructor or in a previous call to + this function is deleted. + + This doesn't change the old log target value (the one the messages are + forwarded to) which still remains the same as was active when wxLogChain + object was created. + */ + void SetLog(wxLog * logger); +}; + + +/** + @class wxLogGui + @wxheader{log.h} + + This is the default log target for the GUI wxWidgets applications. It is passed + to wxLog::SetActiveTarget at the program + startup and is deleted by wxWidgets during the program shut down. + + @library{wxbase} + @category{logging} +*/ +class wxLogGui : public wxLog +{ +public: + /** + Default constructor. + */ + wxLogGui(); +}; + + +/** + @class wxLogStream + @wxheader{log.h} + + This class can be used to redirect the log messages to a C++ stream. + + Please note that this class is only available if wxWidgets was compiled with + the standard iostream library support (@c wxUSE_STD_IOSTREAM must be on). + + @library{wxbase} + @category{logging} + + @seealso + wxLogStderr, wxStreamToTextRedirector +*/ +class wxLogStream : public wxLog +{ +public: + /** + Constructs a log target which sends all the log messages to the given + output stream. If it is @NULL, the messages are sent to @c cerr. + */ + wxLogStream(std::ostream ostr = @NULL); +}; + + +/** + @class wxLogStderr + @wxheader{log.h} + + This class can be used to redirect the log messages to a C file stream (not to + be confused with C++ streams). It is the default log target for the non-GUI + wxWidgets applications which send all the output to @c stderr. + + @library{wxbase} + @category{logging} + + @seealso + wxLogStream +*/ +class wxLogStderr : public wxLog +{ +public: + /** + Constructs a log target which sends all the log messages to the given + @c FILE. If it is @NULL, the messages are sent to @c stderr. + */ + wxLogStderr(FILE fp = @NULL); +}; + + +/** + @class wxLogBuffer + @wxheader{log.h} + + wxLogBuffer is a very simple implementation of log sink which simply collects + all the logged messages in a string (except the debug messages which are output + in the usual way immediately as we're presumably not interested in collecting + them for later). The messages from different log function calls are separated + by the new lines. + + All the messages collected so far can be shown to the user (and the current + buffer cleared) by calling the overloaded wxLogBuffer::Flush + method. + + @library{wxbase} + @category{FIXME} +*/ +class wxLogBuffer : public wxLog +{ +public: + /** + Shows all the messages collected so far to the user (using a message box in the + GUI applications or by printing them out to the console in text mode) and + clears the internal buffer. + */ + virtual void Flush(); + + /** + Returns the current buffer contains. Messages from different log function calls + are separated with the new lines in the buffer. + + The buffer can be cleared by Flush() which will + also show the current contents to the user. + */ + const wxString GetBuffer(); +}; + + +/** + @class wxLogInterposer + @wxheader{log.h} + + A special version of wxLogChain which uses itself as the + new log target. It forwards log messages to the previously installed one in + addition to + processing them itself. + + Unlike wxLogChain which is usually used directly as is, + this class must be derived from to implement wxLog::DoLog + and/or wxLog::DoLogString methods. + + wxLogInterposer destroys the previous log target in its destructor. If you + don't want this to happen, use wxLogInterposerTemp instead. + + @library{wxbase} + @category{logging} +*/ +class wxLogInterposer : public wxLogChain +{ +public: + /** + The default constructor installs this object as the current active log target. + */ +}; + + +/** + @class wxLogTextCtrl + @wxheader{log.h} + + Using these target all the log messages can be redirected to a text control. + The text control must have been created with @c wxTE_MULTILINE style by the + caller previously. + + @library{wxbase} + @category{logging} + + @seealso + wxTextCtrl, wxStreamToTextRedirector +*/ +class wxLogTextCtrl : public wxLog +{ +public: + /** + Constructs a log target which sends all the log messages to the given text + control. The @e textctrl parameter cannot be @NULL. + */ + wxLogTextCtrl(wxTextCtrl textctrl); +}; + + +/** + @class wxLog + @wxheader{log.h} + + wxLog class defines the interface for the @e log targets used by wxWidgets + logging functions as explained in the @ref overview_wxlogoverview "wxLog + overview". + The only situations when you need to directly use this class is when you want + to derive your own log target because the existing ones don't satisfy your + needs. Another case is if you wish to customize the behaviour of the standard + logging classes (all of which respect the wxLog settings): for example, set + which trace messages are logged and which are not or change (or even remove + completely) the timestamp on the messages. + + Otherwise, it is completely hidden behind the @e wxLogXXX() functions and + you may not even know about its existence. + + See @ref overview_wxlogoverview "log overview" for the descriptions of wxWidgets + logging facilities. + + @library{wxcore} + @category{logging} + + @seealso + wxLog::RemoveTraceMask, wxLog::GetTraceMasks +*/ +class wxLog +{ +public: + /** + Add the @e mask to the list of allowed masks for + wxLogTrace. + + @sa RemoveTraceMask(), GetTraceMasks() + */ + static void AddTraceMask(const wxString& mask); + + /** + Removes all trace masks previously set with + AddTraceMask(). + + @sa RemoveTraceMask() + */ + static void ClearTraceMasks(); + + /** + The functions below allow some limited customization of wxLog behaviour + without writing a new log target class (which, aside of being a matter of + several minutes, allows you to do anything you want). + + The verbose messages are the trace messages which are not disabled in the + release mode and are generated by wxLogVerbose. They + are not normally shown to the user because they present little interest, but + may be activated, for example, in order to help the user find some program + problem. + + As for the (real) trace messages, their handling depends on the settings of + the (application global) @e trace mask. There are two ways to specify it: + either by using SetTraceMask() and + GetTraceMask() and using + wxLogTrace which takes an integer mask or by using + AddTraceMask() for string trace masks. + + The difference between bit-wise and string trace masks is that a message using + integer trace mask will only be logged if all bits of the mask are set in the + current mask while a message using string mask will be logged simply if the + mask had been added before to the list of allowed ones. + + For example, + will do something only if the current trace mask contains both + @c wxTraceRefCount and @c wxTraceOle, but + will log the message if it was preceded by + Using string masks is simpler and allows to easily add custom ones, so this is + the preferred way of working with trace messages. The integer trace mask is + kept for compatibility and for additional (but very rarely needed) flexibility + only. + + The standard trace masks are given in wxLogTrace + documentation. + + Finally, the @e wxLog::DoLog() function automatically prepends a time stamp + to all the messages. The format of the time stamp may be changed: it can be + any string with % specifications fully described in the documentation of the + standard @e strftime() function. For example, the default format is + "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] " + (without quotes) for the current date. Setting an empty string as the time + format disables timestamping of the messages completely. + + @b NB: Timestamping is disabled for Visual C++ users in debug builds by + default because otherwise it would be impossible to directly go to the line + from which the log message was generated by simply clicking in the debugger + window on the corresponding error message. If you wish to enable it, please use + SetTimestamp() explicitly. + + AddTraceMask() + + RemoveTraceMask() + + ClearTraceMasks() + + GetTraceMasks() + + IsAllowedTraceMask() + + SetVerbose() + + GetVerbose() + + SetTimestamp() + + GetTimestamp() + + SetTraceMask() + + GetTraceMask() + + SetRepetitionCounting() + + GetRepetitionCounting() + */ + + + /** + Disables time stamping of the log messages. + + This function is new since wxWidgets version 2.9 + */ + void SetTimestamp(const wxString& format); + + /** + Called to process the message of the specified severity. @e msg is the text + of the message as specified in the call of @e wxLogXXX() function which + generated it and @e timestamp is the moment when the message was generated. + + The base class version prepends the timestamp to the message, adds a prefix + corresponding to the log level and then calls + DoLogString() with the resulting string. + */ + virtual void DoLog(wxLogLevel level, const wxString& msg, + time_t timestamp); + + /** + Called to log the specified string. The timestamp is already included in the + string but still passed to this function. + + A simple implementation may just send the string to @c stdout or, better, + @c stderr. + */ + virtual void DoLogString(const wxString& msg, time_t timestamp); + + /** + Instructs wxLog to not create new log targets on the fly if there is none + currently. (Almost) for internal use only: it is supposed to be called by the + application shutdown code. + + Note that this function also calls + ClearTraceMasks(). + */ + static void DontCreateOnDemand(); + + /** + Shows all the messages currently in buffer and clears it. If the buffer + is already empty, nothing happens. + */ + virtual void Flush(); + + /** + Flushes the current log target if any, does nothing if there is none. + + @sa Flush() + */ + static void FlushActive(); + + /** + Returns the pointer to the active log target (may be @NULL). + */ + static wxLog * GetActiveTarget(); + + /** + Returns the current log level limit. + */ + static wxLogLevel GetLogLevel(); + + /** + Returns whether the repetition counting mode is enabled. + */ + static bool GetRepetitionCounting(); + + /** + Returns the current timestamp format string. + */ + static const wxString GetTimestamp(); + + /** + Returns the current trace mask, see Customization() section + for details. + */ + static wxTraceMask GetTraceMask(); + + /** + Returns the currently allowed list of string trace masks. + + @sa AddTraceMask(). + */ + static const wxArrayString GetTraceMasks(); + + /** + Returns whether the verbose mode is currently active. + */ + static bool GetVerbose(); + + /** + The functions in this section work with and manipulate the active log target. + The OnLog() is called by the @e wxLogXXX() functions + and invokes the DoLog() of the active log target if any. + Get/Set methods are used to install/query the current active target and, + finally, DontCreateOnDemand() disables the + automatic creation of a standard log target if none actually exists. It is + only useful when the application is terminating and shouldn't be used in other + situations because it may easily lead to a loss of messages. + + OnLog() + + GetActiveTarget() + + SetActiveTarget() + + DontCreateOnDemand() + + Suspend() + + Resume() + */ + + + /** + Returns @true if the @e mask is one of allowed masks for + wxLogTrace. + + See also: AddTraceMask(), + RemoveTraceMask() + */ + static bool IsAllowedTraceMask(const wxString& mask); + + /** + There are two functions which must be implemented by any derived class to + actually process the log messages: DoLog() and + DoLogString(). The second function receives a string + which just has to be output in some way and the easiest way to write a new log + target is to override just this function in the derived class. If more control + over the output format is needed, then the first function must be overridden + which allows to construct custom messages depending on the log level or even + do completely different things depending on the message severity (for example, + throw away all messages except warnings and errors, show warnings on the + screen and forward the error messages to the user's (or programmer's) cell + phone - maybe depending on whether the timestamp tells us if it is day or + night in the current time zone). + + There also functions to support message buffering. Why are they needed? + Some of wxLog implementations, most notably the standard wxLogGui class, + buffer the messages (for example, to avoid showing the user a zillion of modal + message boxes one after another -- which would be really annoying). + Flush() shows them all and clears the buffer contents. + This function doesn't do anything if the buffer is already empty. + + Flush() + + FlushActive() + */ + + + /** + Forwards the message at specified level to the @e DoLog() function of the + active log target if there is any, does nothing otherwise. + */ + static void OnLog(wxLogLevel level, const wxString& message); + + /** + Remove the @e mask from the list of allowed masks for + wxLogTrace. + + See also: AddTraceMask() + */ + static void RemoveTraceMask(const wxString& mask); + + /** + Resumes logging previously suspended by a call to + Suspend(). All messages logged in the meanwhile will be + flushed soon. + */ + static void Resume(); + + /** + Sets the specified log target as the active one. Returns the pointer to the + previous active log target (may be @NULL). To suppress logging use a new + instance of wxLogNull not @NULL. If the active log target is set to @NULL a + new default log target will be created when logging occurs. + */ + static wxLog * SetActiveTarget(wxLog * logtarget); + + /** + Specifies that log messages with level logLevel should be ignored + and not sent to the active log target. + */ + static void SetLogLevel(wxLogLevel logLevel); + + /** + Enables logging mode in which a log message is logged once, and in case exactly + the same message successively repeats one or more times, only the number of + repetitions is logged. + */ + static void SetRepetitionCounting(bool repetCounting = @true); + + /** + Sets the timestamp format prepended by the default log targets to all + messages. The string may contain any normal characters as well as % + prefixed format specificators, see @e strftime() manual for details. + Passing an empty string to this function disables message time stamping. + */ + static void SetTimestamp(const wxString& format); + + /** + Sets the trace mask, see Customization() + section for details. + */ + static void SetTraceMask(wxTraceMask mask); + + /** + Activates or deactivates verbose mode in which the verbose messages are + logged as the normal ones instead of being silently dropped. + */ + static void SetVerbose(bool verbose = @true); + + /** + Suspends the logging until Resume() is called. Note that + the latter must be called the same number of times as the former to undo it, + i.e. if you call Suspend() twice you must call Resume() twice as well. + + Note that suspending the logging means that the log sink won't be be flushed + periodically, it doesn't have any effect if the current log target does the + logging immediately without waiting for Flush() to be + called (the standard GUI log target only shows the log dialog when it is + flushed, so Suspend() works as expected with it). + + @sa Resume(), wxLogNull + */ + static void Suspend(); +}; + + +/** + @class wxLogNull + @wxheader{log.h} + + This class allows to temporarily suspend logging. All calls to the log + functions during the life time of an object of this class are just ignored. + + In particular, it can be used to suppress the log messages given by wxWidgets + itself but it should be noted that it is rarely the best way to cope with this + problem as @b all log messages are suppressed, even if they indicate a + completely different error than the one the programmer wanted to suppress. + + For instance, the example of the overview: + + @code + wxFile file; + + // wxFile.Open() normally complains if file can't be opened, we don't want it + { + wxLogNull logNo; + if ( !file.Open("bar") ) + ... process error ourselves ... + } // ~wxLogNull called, old log sink restored + + wxLogMessage("..."); // ok + @endcode + + would be better written as: + + @code + wxFile file; + + // don't try to open file if it doesn't exist, we are prepared to deal with + // this ourselves - but all other errors are not expected + if ( wxFile::Exists("bar") ) + { + // gives an error message if the file couldn't be opened + file.Open("bar"); + } + else + { + ... + } + @endcode + + + @library{wxbase} + @category{logging} +*/ +class wxLogNull : public wxLog +{ +public: + /** + Suspends logging. + */ + wxLogNull(); + + /** + Resumes logging. + */ +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + This function shows a message to the user in a safe way and should be safe to + call even before the application has been initialized or if it is currently in + some other strange state (for example, about to crash). Under Windows this + function shows a message box using a native dialog instead of + wxMessageBox (which might be unsafe to call), elsewhere + it simply prints the message to the standard output using the title as prefix. + + @param title + The title of the message box shown to the user or the prefix + of the message string + + @param text + The text to show to the user + + @sa wxLogFatalError +*/ +void wxSafeShowMessage(const wxString& title, + const wxString& text); + diff --git a/interface/longlong.h b/interface/longlong.h new file mode 100644 index 0000000000..b98f782647 --- /dev/null +++ b/interface/longlong.h @@ -0,0 +1,187 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: longlong.h +// Purpose: documentation for wxLongLong class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxLongLong + @wxheader{longlong.h} + + This class represents a signed 64 bit long number. It is implemented using the + native 64 bit type where available (machines with 64 bit longs or compilers + which have (an analog of) @e long long type) and uses the emulation code in + the other cases which ensures that it is the most efficient solution for + working with 64 bit integers independently of the architecture. + + wxLongLong defines all usual arithmetic operations such as addition, + subtraction, bitwise shifts and logical operations as well as multiplication + and division (not yet for the machines without native @e long long). It + also has operators for implicit construction from and conversion to the native + @e long long type if it exists and @e long. + + You would usually use this type in exactly the same manner as any other + (built-in) arithmetic type. Note that wxLongLong is a signed type, if you + want unsigned values use wxULongLong which has exactly the same API as + wxLongLong except when explicitly mentioned otherwise. + + If a native (i.e. supported directly by the compiler) 64 bit integer type was + found to exist, @e wxLongLong_t macro will be defined to correspond to it. + Also, in this case only, two additional macros will be defined: + wxLongLongFmtSpec for printing 64 bit integers + using the standard @c printf() function (but see also + wxLongLong::ToString for a more portable solution) and + wxLL for defining 64 bit integer compile-time constants. + + @library{wxbase} + @category{data} +*/ +class wxLongLong +{ +public: + /** + Constructor from 2 longs: the high and low part are combined into one + wxLongLong. + */ + wxLongLong(long hi, unsigned long lo); + + //@{ + /** + Returns an absolute value of wxLongLong - either making a copy (const version) + or modifying it in place (the second one). Not in wxULongLong. + */ + wxLongLong Abs(); + wxLongLong Abs(); + //@} + + /** + This allows to convert a double value to wxLongLong type. Such conversion is + not always possible in which case the result will be silently truncated in a + platform-dependent way. Not in wxULongLong. + */ + wxLongLong Assign(double d); + + /** + Returns the high 32 bits of 64 bit integer. + */ + long GetHi(); + + /** + Returns the low 32 bits of 64 bit integer. + */ + unsigned long GetLo(); + + /** + Convert to native long long (only for compilers supporting it) + */ + wxLongLong_t GetValue(); + + /** + Returns the value as @c double. + */ + double ToDouble(); + + /** + Truncate wxLongLong to long. If the conversion loses data (i.e. the wxLongLong + value is outside the range of built-in long type), an assert will be triggered + in debug mode. + */ + long ToLong(); + + /** + Returns the string representation of a wxLongLong. + */ + wxString ToString(); + + /** + Adds 2 wxLongLongs together and returns the result. + */ + wxLongLong operator+(const wxLongLong& ll); + + //@{ + /** + Pre/post increment operator. + */ + wxLongLong operator++(); + wxLongLong operator++(int ); + //@} + + /** + Add another wxLongLong to this one. + */ + wxLongLong operator+(const wxLongLong& ll); + + /** + Subtracts 2 wxLongLongs and returns the result. + */ + wxLongLong operator-(const wxLongLong& ll); + + //@{ + /** + Pre/post decrement operator. + */ + wxLongLong operator--(); + wxLongLong operator--(int ); + //@} + + /** + Subtracts another wxLongLong from this one. + */ + wxLongLong operator-(const wxLongLong& ll); + + /** + Assignment operator from unsigned long long. The sign bit will be copied too. + + This function is new since wxWidgets version 2.7.0 + */ + wxLongLong& operator operator=(const wxULongLong & ll); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + This macro is defined to contain the @c printf() format specifier using + which 64 bit integer numbers (i.e. those of type @c wxLongLong_t) can be + printed. Example of using it: + @code + #ifdef wxLongLong_t + wxLongLong_t ll = wxLL(0x1234567890abcdef); + printf("Long long = %" wxLongLongFmtSpec "x\n", ll); + #endif + @endcode + + @sa wxLL +*/ + + +/** + This macro is defined for the platforms with a native 64 bit integer type and + allows to define unsigned 64 bit compile time constants: + @code + #ifdef wxLongLong_t + unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef); + #endif + @endcode + + @sa wxLL, wxLongLong +*/ +#define wxLongLong_t wxULL(number) /* implementation is private */ + +/** + This macro is defined for the platforms with a native 64 bit integer type and + allows to define 64 bit compile time constants: + @code + #ifdef wxLongLong_t + wxLongLong_t ll = wxLL(0x1234567890abcdef); + #endif + @endcode + + @sa wxULL, wxLongLong +*/ +#define wxLongLong_t wxLL(number) /* implementation is private */ + diff --git a/interface/math.h b/interface/math.h new file mode 100644 index 0000000000..db1265755e --- /dev/null +++ b/interface/math.h @@ -0,0 +1,16 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: math.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + Returns a non-zero value if @e x is neither infinite nor NaN (not a number), + returns 0 otherwise. +*/ +int wxFinite(double x); + + + \ No newline at end of file diff --git a/interface/mdi.h b/interface/mdi.h new file mode 100644 index 0000000000..eea1573120 --- /dev/null +++ b/interface/mdi.h @@ -0,0 +1,418 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: mdi.h +// Purpose: documentation for wxMDIClientWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMDIClientWindow + @wxheader{mdi.h} + + An MDI client window is a child of wxMDIParentFrame, and manages zero or + more wxMDIChildFrame objects. + + @library{wxcore} + @category{FIXME} + + @seealso + wxMDIChildFrame, wxMDIParentFrame, wxFrame +*/ +class wxMDIClientWindow : public wxWindow +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent. + + @param style + The window style. Currently unused. + + @remarks The second style of constructor is called within + wxMDIParentFrame::OnCreateClient. + + @sa wxMDIParentFrame::wxMDIParentFrame, wxMDIParentFrame::OnCreateClient + */ + wxMDIClientWindow(); + wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0); + //@} + + /** + Destructor. + */ + ~wxMDIClientWindow(); + + /** + Used in two-step frame construction. See wxMDIClientWindow() + for further details. + */ + bool CreateClient(wxMDIParentFrame* parent, long style = 0); +}; + + +/** + @class wxMDIParentFrame + @wxheader{mdi.h} + + An MDI (Multiple Document Interface) parent frame is a window which can contain + MDI child frames in its own 'desktop'. It is a convenient way to avoid window + clutter, + and is used in many popular Windows applications, such as Microsoft Word(TM). + + @beginStyleTable + @style{wxCAPTION}: + Puts a caption on the frame. + @style{wxDEFAULT_FRAME_STYLE}: + Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxTHICK_FRAME | + wxSYSTEM_MENU | wxCAPTION. + @style{wxHSCROLL}: + Displays a horizontal scrollbar in the client window, allowing the + user to view child frames that are off the current view. + @style{wxICONIZE}: + Display the frame iconized (minimized) (Windows only). + @style{wxMAXIMIZE}: + Displays the frame maximized (Windows only). + @style{wxMAXIMIZE_BOX}: + Displays a maximize box on the frame (Windows and Motif only). + @style{wxMINIMIZE}: + Identical to wxICONIZE. + @style{wxMINIMIZE_BOX}: + Displays a minimize box on the frame (Windows and Motif only). + @style{wxRESIZE_BORDER}: + Displays a resizeable border around the window (Motif only; for + Windows, it is implicit in wxTHICK_FRAME). + @style{wxSTAY_ON_TOP}: + Stay on top of other windows (Windows only). + @style{wxSYSTEM_MENU}: + Displays a system menu (Windows and Motif only). + @style{wxTHICK_FRAME}: + Displays a thick frame around the window (Windows and Motif only). + @style{wxVSCROLL}: + Displays a vertical scrollbar in the client window, allowing the + user to view child frames that are off the current view. + @style{wxFRAME_NO_WINDOW_MENU}: + Under Windows, removes the Window menu that is normally added + automatically. + @endStyleTable + + @library{wxcore} + @category{managedwnd} + + @seealso + wxMDIChildFrame, wxMDIClientWindow, wxFrame, wxDialog +*/ +class wxMDIParentFrame : public wxFrame +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent. This should be @NULL. + + @param id + The window identifier. It may take a value of -1 to indicate a default value. + + @param title + The caption to be displayed on the frame's title bar. + + @param pos + The window position. The value wxDefaultPosition indicates a default position, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param size + The window size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param style + The window style. See wxMDIParentFrame. + + @param name + The name of the window. This parameter is used to associate a name with the + item, + allowing the application user to set Motif resource values for + individual windows. + + @remarks During the construction of the frame, the client window will be + created. To use a different class from + wxMDIClientWindow, override + OnCreateClient(). + + @sa Create(), OnCreateClient() + */ + wxMDIParentFrame(); + wxMDIParentFrame(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, + const wxString& name = "frame"); + //@} + + /** + Destructor. Destroys all child windows and menu bar if present. + */ + ~wxMDIParentFrame(); + + /** + Activates the MDI child following the currently active one. + + @sa ActivatePrevious() + */ + void ActivateNext(); + + /** + Activates the MDI child preceding the currently active one. + + @sa ActivateNext() + */ + void ActivatePrevious(); + + /** + Arranges any iconized (minimized) MDI child windows. + + @sa Cascade(), Tile() + */ + void ArrangeIcons(); + + /** + Arranges the MDI child windows in a cascade. + + @sa Tile(), ArrangeIcons() + */ + void Cascade(); + + /** + Used in two-step frame construction. See wxMDIParentFrame() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, + const wxString& name = "frame"); + + /** + Returns a pointer to the active MDI child, if there is one. + */ + wxMDIChildFrame* GetActiveChild(); + + /** + This gets the size of the frame 'client area' in pixels. + + @param width + Receives the client width in pixels. + + @param height + Receives the client height in pixels. + + @remarks The client area is the area which may be drawn on by the + programmer, excluding title bar, border, status bar, + and toolbar if present. + + @sa GetToolBar(), SetToolBar(), + wxMDIClientWindow + */ + virtual void GetClientSize(int* width, int* height); + + /** + Returns a pointer to the client window. + + @sa OnCreateClient() + */ + wxMDIClientWindow* GetClientWindow(); + + /** + Returns the window being used as the toolbar for this frame. + + @sa SetToolBar() + */ + virtual wxWindow* GetToolBar(); + + /** + Returns the current Window menu (added by wxWidgets to the menubar). This + function + is available under Windows only. + */ + wxMenu* GetWindowMenu(); + + /** + Override this to return a different kind of client window. If you override this + function, + you must create your parent frame in two stages, or your function will never be + called, + due to the way C++ treats virtual functions called from constructors. For + example: + + @remarks You might wish to derive from wxMDIClientWindow in order to + implement different erase behaviour, for example, + such as painting a bitmap on the background. + + @sa GetClientWindow(), wxMDIClientWindow + */ + virtual wxMDIClientWindow* OnCreateClient(); + + /** + Sets the window to be used as a toolbar for this + MDI parent window. It saves the application having to manage the positioning + of the toolbar MDI client window. + + @param toolbar + Toolbar to manage. + + @remarks When the frame is resized, the toolbar is resized to be the + width of the frame client area, and the toolbar + height is kept the same. + + @sa GetToolBar(), GetClientSize() + */ + virtual void SetToolBar(wxWindow* toolbar); + + /** + Call this to change the current Window menu. Ownership of the menu object + passes to + the frame when you call this function. + + This call is available under Windows only. + + To remove the window completely, use the wxFRAME_NO_WINDOW_MENU window style. + */ + void SetWindowMenu(wxMenu* menu); + + /** + Tiles the MDI child windows either horizontally or vertically depending on + whether @e orient is wxHORIZONTAL or wxVERTICAL. + + Currently only implemented for MSW, does nothing under the other platforms. + */ + void Tile(wxOrientation orient = wxHORIZONTAL); +}; + + +/** + @class wxMDIChildFrame + @wxheader{mdi.h} + + An MDI child frame is a frame that can only exist on a wxMDIClientWindow, + which is itself a child of wxMDIParentFrame. + + @beginStyleTable + @style{wxCAPTION}: + Puts a caption on the frame. + @style{wxDEFAULT_FRAME_STYLE}: + Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxTHICK_FRAME | + wxSYSTEM_MENU | wxCAPTION. + @style{wxICONIZE}: + Display the frame iconized (minimized) (Windows only). + @style{wxMAXIMIZE}: + Displays the frame maximized (Windows only). + @style{wxMAXIMIZE_BOX}: + Displays a maximize box on the frame (Windows and Motif only). + @style{wxMINIMIZE}: + Identical to wxICONIZE. + @style{wxMINIMIZE_BOX}: + Displays a minimize box on the frame (Windows and Motif only). + @style{wxRESIZE_BORDER}: + Displays a resizeable border around the window (Motif only; for + Windows, it is implicit in wxTHICK_FRAME). + @style{wxSTAY_ON_TOP}: + Stay on top of other windows (Windows only). + @style{wxSYSTEM_MENU}: + Displays a system menu (Windows and Motif only). + @style{wxTHICK_FRAME}: + Displays a thick frame around the window (Windows and Motif only). + @endStyleTable + + @library{wxcore} + @category{managedwnd} + + @seealso + wxMDIClientWindow, wxMDIParentFrame, wxFrame +*/ +class wxMDIChildFrame : public wxFrame +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent. This should not be @NULL. + + @param id + The window identifier. It may take a value of -1 to indicate a default value. + + @param title + The caption to be displayed on the frame's title bar. + + @param pos + The window position. The value wxDefaultPosition indicates a default position, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param size + The window size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param style + The window style. See wxMDIChildFrame. + + @param name + The name of the window. This parameter is used to associate a name with the + item, + allowing the application user to set Motif resource values for + individual windows. + + @remarks None. + + @sa Create() + */ + wxMDIChildFrame(); + wxMDIChildFrame(wxMDIParentFrame* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + //@} + + /** + Destructor. Destroys all child windows and menu bar if present. + */ + ~wxMDIChildFrame(); + + /** + Activates this MDI child frame. + + @sa Maximize(), Restore() + */ + void Activate(); + + /** + Used in two-step frame construction. See wxMDIChildFrame() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Maximizes this MDI child frame. + + @sa Activate(), Restore() + */ + void Maximize(bool maximize); + + /** + Restores this MDI child frame (unmaximizes). + */ + void Restore(); +}; diff --git a/interface/mediactrl.h b/interface/mediactrl.h new file mode 100644 index 0000000000..2b4f3366ea --- /dev/null +++ b/interface/mediactrl.h @@ -0,0 +1,439 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: mediactrl.h +// Purpose: documentation for wxMediaEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMediaEvent + @wxheader{mediactrl.h} + + Event wxMediaCtrl uses. + + @library{wxmedia} + @category{FIXME} +*/ +class wxMediaEvent : public wxNotifyEvent +{ +public: + +}; + + +/** + @class wxMediaCtrl + @wxheader{mediactrl.h} + + wxMediaCtrl is a class for displaying types of + media, such as videos, audio files, natively through native codecs. + + wxMediaCtrl uses native backends to render media, for example on Windows + there is a ActiveMovie/DirectShow backend, and on Macintosh there is a + QuickTime backend. + + @library{wxmedia} + @category{media} + + @seealso + wxMediaEvent +*/ +class wxMediaCtrl : public wxControl +{ +public: + //@{ + /** + , + @b const wxPoint& + + @param pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& szBackend = wxT(""), + const wxValidatorvalidator = wxDefaultValidator, + const wxString& name = wxPanelNameStr + ) + + Constructor that calls Create. You may prefer to call Create directly to check + to see if wxMediaCtrl is available on the system. + + parent + parent of this control. Must not be @NULL. + + @param id + id to use for events + + @param fileName + If not empty, the path of a file to open. + + @param pos + Position to put control at. + + @param size + Size to put the control at and to stretch movie to. + + @param style + Optional styles. + + @param szBackend + Name of backend you want to use, leave blank to make + wxMediaCtrl figure it out. + + @param validator + validator to use. + + @param name + Window name. + */ + wxMediaCtrl(); + wxMediaCtrl(wxWindow* parent, wxWindowID id); + //@} + + /** + Generally, you should almost certainly leave this part up to + wxMediaCtrl - but if you need a certain backend for a particular + reason, such as QuickTime for playing .mov files, all you need + to do to choose a specific backend is to pass the + name of the backend class to + Create(). + + The following are valid backend identifiers - + + @b wxMEDIABACKEND_DIRECTSHOW + + + + Use ActiveMovie/DirectShow. Uses the native ActiveMovie + (I.E. DirectShow) control. Default backend on Windows and + supported by nearly all Windows versions, even some + Windows CE versions. May display a windows media player + logo while inactive. + + @b wxMEDIABACKEND_QUICKTIME + + + Use QuickTime. Mac Only. + WARNING: May not working correctly embedded in a wxNotebook. + + + @b wxMEDIABACKEND_GSTREAMER + + + Use GStreamer. Unix Only. Requires GStreamer 0.8 along + with at the very least the xvimagesink, xoverlay, and + gst-play modules of gstreamer to function. You need the correct + modules to play the relavant files, for example the mad module + to play mp3s, etc. + + @b wxMEDIABACKEND_WMP10 + + + Uses Windows Media Player 10 (Windows only) - works on mobile + machines with Windows Media Player 10 and desktop machines with + either Windows Media Player 9 or 10 + + Note that other backends such as wxMEDIABACKEND_MCI can now be + found at wxCode. + */ + + + /** + , + @b const wxPoint& + + @param pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& szBackend = wxT(""), + const wxValidatorvalidator = wxDefaultValidator, + const wxString& name = wxPanelNameStr + ) + + Creates this control. Returns @false if it can't load the movie located at + fileName or it cannot load one of its native backends. + + If you specify a file to open via fileName and you don't specify a backend to + use, wxMediaCtrl tries each of its backends until one that can render the path referred to by fileName can be found. + + parent + parent of this control. Must not be @NULL. + + @param id + id to use for events + + @param fileName + If not empty, the path of a file to open. + + @param pos + Position to put control at. + + @param size + Size to put the control at and to stretch movie to. + + @param style + Optional styles. + + @param szBackend + Name of backend you want to use, leave blank to make + wxMediaCtrl figure it out. + + @param validator + validator to use. + + @param name + Window name. + */ + bool Create(wxWindow* parent, wxWindowID id); + + /** + Creating a backend for wxMediaCtrl is a rather simple process. Simply derive + from wxMediaBackendCommonBase and implement the methods you want. The methods + in wxMediaBackend correspond to those in wxMediaCtrl except for CreateControl + which does the actual creation of the control, in cases where a custom control + is not needed you may simply call wxControl::Create. + + You need to make sure to use the DECLARE_CLASS and IMPLEMENT_CLASS macros. + + The only real tricky part is that you need to make sure the file in compiled + in, which if there are just backends in there will not happen and you may need + to use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI). + + This is a rather simple example of how to create a backend in the + wxActiveXContainer documentation. + */ + + + /** + Obtains the best size relative to the original/natural size of the + video, if there is any. See @ref overview_videosizewxmediactrl "Video size" + for more information. + */ + wxSize GetBestSize(); + + /** + Obtains the playback rate, or speed of the media. @c 1.0 represents normal + speed, while @c 2.0 represents twice the normal speed of the media, for + example. Not supported on the GStreamer (Unix) backend. + Returns 0 on failure. + */ + double GetPlaybackrate(); + + /** + Obtains the state the playback of the media is in - + + + @b wxMEDIASTATE_STOPPED + + + The movie has stopped. + + @b wxMEDIASTATE_PAUSED + + + The movie is paused. + + @b wxMEDIASTATE_PLAYING + + + The movie is currently playing. + */ + wxMediaCtrlState GetState(); + + /** + Gets the volume of the media from a 0.0 to 1.0 range. Note that due to rounding + and other errors this may not be the exact value sent to SetVolume. + */ + double GetVolume(); + + /** + Obtains the length - the total amount of time the movie has in milliseconds. + */ + wxFileOffset Length(); + + /** + Loads the location that @c uri refers to with the proxy @c proxy. Not + implemented on most backends so it should be called with caution. Returns @false if loading fails. + */ + bool Load(const wxURI& uri, const wxURI& proxy); + + /** + Same as @ref loaduri() Load. Kept for wxPython compatability. + */ + bool LoadURI(const wxURI& uri); + + /** + Same as @ref loaduriwithproxy() Load. Kept for wxPython compatability. + */ + bool LoadURIWithProxy(const wxURI& uri, const wxURI& proxy); + + /** + When wxMediaCtrl plays a file, it plays until the stop position + is reached (currently the end of the file/stream). Right before + it hits the end of the stream, it fires off a EVT_MEDIA_STOP + event to its parent window, at which point the event handler + can choose to veto the event, preventing the stream from actually + stopping. + + Example: + + When wxMediaCtrl stops, either by the EVT_MEDIA_STOP not being + vetoed, or by manually calling + Stop(), where it actually + stops is not at the beginning, rather, but at the beginning of + the stream. That is, when it stops and play is called, playback + is gauranteed to start at the beginning of the media. This is + because some streams are not seekable, and when stop is called + on them they return to the beginning, thus wxMediaCtrl tries + to keep consistant for all types of media. + + Note that when changing the state of the media through Play() + and other methods, the media may not actually be in the + wxMEDIASTATE_PLAYING, for example. If you are relying on the + media being in certain state catch the event relevant to the state. + See wxMediaEvent for the kinds of events + that you can catch. + */ + + + /** + Pauses playback of the movie. + */ + bool Pause(); + + /** + Resumes playback of the movie. + */ + bool Play(); + + /** + Normally, when you use wxMediaCtrl it is just a window for the video to + play in. However, some toolkits have their own media player interface. + For example, QuickTime generally has a bar below the video with a slider. + A special feature available to wxMediaCtrl, you can use the toolkit's interface + instead of + making your own by using the ShowPlayerControls() + function. There are several options for the flags parameter, with + the two general flags being wxMEDIACTRLPLAYERCONTROLS_NONE which turns off + the native interface, and wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets + wxMediaCtrl decide what native controls on the interface. Be sure to review + the caveats outlined in @ref overview_videosizewxmediactrl "Video size" before + doing so. + */ + + + /** + Depending upon the backend, wxMediaCtrl can render + and display pretty much any kind of media that the native system can - + such as an image, mpeg video, or mp3 (without license restrictions - + since it relies on native system calls that may not technically + have mp3 decoding available, for example, it falls outside the + realm of licensing restrictions). + + For general operation, all you need to do is call + Load() to load the file + you want to render, catch the EVT_MEDIA_LOADED event, + and then call Play() + to show the video/audio of the media in that event. + + More complex operations are generally more heavily dependant on the + capabilities of the backend. For example, QuickTime cannot set + the playback rate of certain streaming media - while DirectShow is + slightly more flexible in that regard. + */ + + + /** + Seeks to a position within the movie. + */ + wxFileOffset Seek(wxFileOffset where, wxSeekMode mode); + + /** + Sets the playback rate, or speed of the media, to that referred by @c dRate. + @c 1.0 represents normal speed, while @c 2.0 represents twice the normal + speed of the media, for example. Not supported on the GStreamer (Unix) backend. + Returns @true if successful. + */ + bool SetPlaybackRate(double dRate); + + /** + Sets the volume of the media from a 0.0 to 1.0 range to that referred + by @c dVolume. @c 1.0 represents full volume, while @c 0.5 + represents half (50 percent) volume, for example. Note that this may not be + exact due to conversion and rounding errors, although setting the volume to + full or none is always exact. Returns @true if successful. + */ + bool SetVolume(double dVolume); + + /** + A special feature to wxMediaCtrl. Applications using native toolkits such as + QuickTime usually have a scrollbar, play button, and more provided to + them by the toolkit. By default wxMediaCtrl does not do this. However, on + the directshow and quicktime backends you can show or hide the native controls + provided by the underlying toolkit at will using ShowPlayerControls. Simply + calling the function with default parameters tells wxMediaCtrl to use the + default controls provided by the toolkit. The function takes a + @c wxMediaCtrlPlayerControls enumeration as follows: + + + @b wxMEDIACTRLPLAYERCONTROLS_NONE + + + No controls. return wxMediaCtrl to it's default state. + + @b wxMEDIACTRLPLAYERCONTROLS_STEP + + + Step controls like fastfoward, step one frame etc. + + @b wxMEDIACTRLPLAYERCONTROLS_VOLUME + + + Volume controls like the speaker icon, volume slider, etc. + + @b wxMEDIACTRLPLAYERCONTROLS_DEFAULT + + + Default controls for the toolkit. Currently a typedef for + wxMEDIACTRLPLAYERCONTROLS_STEP and wxMEDIACTRLPLAYERCONTROLS_VOLUME. + + For more see @ref overview_playercontrolswxmediactrl "Player controls". + Currently + only implemented on the QuickTime and DirectShow backends. The function + returns @true on success. + */ + bool ShowPlayerControls(wxMediaCtrlPlayerControls flags = wxMEDIACTRLPLAYERCONTROLS_DEFAULT); + + /** + Stops the media. + + See Operation for an overview of how + stopping works. + */ + bool Stop(); + + /** + Obtains the current position in time within the movie in milliseconds. + */ + wxFileOffset Tell(); + + /** + By default, wxMediaCtrl will scale the size of the video to the + requested amount passed to either it's constructor or Create(). + After calling Load or performing an equivilant operation, you + can subsequently obtain the "real" size of the video (if there + is any) by calling GetBestSize(). Note that the actual result + on the display will be slightly different when ShowPlayerControls + is activated and the actual video size will be less then + specified due to the extra controls provided by the native toolkit. + In addition, the backend may modify GetBestSize() to include the + size of the extra controls - so if you want the real size of the + video just disable ShowPlayerControls(). + + The idea with setting GetBestSize to the size of the video is + that GetBestSize is a wxWindow-derived function that is called + when sizers on a window recalculate. What this means is that + if you use sizers by default the video will show in it's + original size without any extra assistance needed from the user. + */ +}; diff --git a/interface/memory.h b/interface/memory.h new file mode 100644 index 0000000000..d2b306d6b4 --- /dev/null +++ b/interface/memory.h @@ -0,0 +1,281 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: memory.h +// Purpose: documentation for wxDebugStreamBuf class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDebugStreamBuf + @wxheader{memory.h} + + This class allows you to treat debugging output in a similar + (stream-based) fashion on different platforms. Under + Windows, an ostream constructed with this buffer outputs + to the debugger, or other program that intercepts debugging + output. On other platforms, the output goes to standard error (cerr). + + This is soon to be obsolete, replaced by wxLog functionality. + + @library{wxbase} + @category{FIXME} + + @seealso + Overview +*/ +class wxDebugStreamBuf +{ +public: + +}; + + +/** + @class wxDebugContext + @wxheader{memory.h} + + A class for performing various debugging and memory tracing + operations. Full functionality (such as printing out objects + currently allocated) is only present in a debugging build of wxWidgets, + i.e. if the __WXDEBUG__ symbol is defined. wxDebugContext + and related functions and macros can be compiled out by setting + wxUSE_DEBUG_CONTEXT to 0 is setup.h + + @library{wxbase} + @category{debugging} + + @seealso + Overview +*/ +class wxDebugContext +{ +public: + /** + Checks the memory blocks for errors, starting from the currently set + checkpoint. + + @returns Returns the number of errors, so a value of zero represents + success. Returns -1 if an error was detected that + prevents further checking. + */ + int Check(); + + /** + Performs a memory dump from the currently set checkpoint, writing to the + current debug stream. Calls the @b Dump member function for each wxObject + derived instance. + + @returns @true if the function succeeded, @false otherwise. + */ + bool Dump(); + + /** + Returns @true if the memory allocator checks all previous memory blocks for + errors. + By default, this is @false since it slows down execution considerably. + + @sa SetCheckPrevious() + */ + bool GetCheckPrevious(); + + /** + Returns @true if debug mode is on. If debug mode is on, the wxObject new and + delete + operators store or use information about memory allocation. Otherwise, + a straight malloc and free will be performed by these operators. + + @sa SetDebugMode() + */ + bool GetDebugMode(); + + /** + Gets the debug level (default 1). The debug level is used by the wxTraceLevel + function and + the WXTRACELEVEL macro to specify how detailed the trace information is; setting + a different level will only have an effect if trace statements in the + application + specify a value other than one. + + This is obsolete, replaced by wxLog functionality. + + @sa SetLevel() + */ + int GetLevel(); + + /** + Returns the output stream associated with the debug context. + + This is obsolete, replaced by wxLog functionality. + + @sa SetStream() + */ + ostream GetStream(); + + /** + Returns a pointer to the output stream buffer associated with the debug context. + There may not necessarily be a stream buffer if the stream has been set + by the user. + + This is obsolete, replaced by wxLog functionality. + */ + streambuf* GetStreamBuf(); + + /** + Returns @true if there is a stream currently associated + with the debug context. + + This is obsolete, replaced by wxLog functionality. + + @sa SetStream(), GetStream() + */ + bool HasStream(); + + /** + Prints a list of the classes declared in this application, giving derivation + and whether instances of this class can be dynamically created. + + @sa PrintStatistics() + */ + bool PrintClasses(); + + /** + Performs a statistics analysis from the currently set checkpoint, writing + to the current debug stream. The number of object and non-object + allocations is printed, together with the total size. + + @param detailed + If @true, the function will also print how many + objects of each class have been allocated, and the space taken by + these class instances. + + @sa PrintStatistics() + */ + bool PrintStatistics(bool detailed = @true); + + /** + Tells the memory allocator to check all previous memory blocks for errors. + By default, this is @false since it slows down execution considerably. + + @sa GetCheckPrevious() + */ + void SetCheckPrevious(bool check); + + /** + Sets the current checkpoint: Dump and PrintStatistics operations will + be performed from this point on. This allows you to ignore allocations + that have been performed up to this point. + + @param all + If @true, the checkpoint is reset to include all + memory allocations since the program started. + */ + void SetCheckpoint(bool all = @false); + + /** + Sets the debug mode on or off. If debug mode is on, the wxObject new and delete + operators store or use information about memory allocation. Otherwise, + a straight malloc and free will be performed by these operators. + + By default, debug mode is on if __WXDEBUG__ is defined. If the application + uses this function, it should make sure that all object memory allocated + is deallocated with the same value of debug mode. Otherwise, the + delete operator might try to look for memory information that does not + exist. + + @sa GetDebugMode() + */ + void SetDebugMode(bool debug); + + /** + Sets the current debug file and creates a stream. This will delete any existing + stream and stream buffer. By default, the debug context stream + outputs to the debugger (Windows) or standard error (other platforms). + */ + bool SetFile(const wxString& filename); + + /** + Sets the debug level (default 1). The debug level is used by the wxTraceLevel + function and + the WXTRACELEVEL macro to specify how detailed the trace information is; setting + a different level will only have an effect if trace statements in the + application + specify a value other than one. + + This is obsolete, replaced by wxLog functionality. + + @sa GetLevel() + */ + void SetLevel(int level); + + /** + Installs a function to be called at the end of wxWidgets shutdown. It will be + called after + all files with global instances of wxDebugContextDumpDelayCounter have run + their destructors. + + The shutdown function must be take no parameters and return nothing. + */ + void SetShutdownNotifyFunction(wxShutdownNotifyFunction func); + + /** + Sets the debugging stream to be the debugger (Windows) or standard error (other + platforms). + This is the default setting. The existing stream will be flushed and deleted. + + This is obsolete, replaced by wxLog functionality. + */ + bool SetStandardError(); + + /** + Sets the stream and optionally, stream buffer associated with the debug context. + This operation flushes and deletes the existing stream (and stream buffer if + any). + + This is obsolete, replaced by wxLog functionality. + + @param stream + Stream to associate with the debug context. Do not set this to @NULL. + + @param streamBuf + Stream buffer to associate with the debug context. + */ + void SetStream(ostream* stream, streambuf* streamBuf = @NULL); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + @b NB: This function is now obsolete, replaced by @ref overview_logfunctions + "Log functions". + + Calls wxTraceLevel with printf-style variable argument syntax. Output + is directed to the current output stream (see wxDebugContext). + The first argument should be the level at which this information is appropriate. + It will only be output if the level returned by wxDebugContext::GetLevel is + equal to or greater than + this value. +*/ +#define WXTRACELEVEL() /* implementation is private */ + +/** + @b NB: This function is now obsolete, replaced by @ref overview_logfunctions + "Log functions". + + Takes printf-style variable argument syntax. Output + is directed to the current output stream (see wxDebugContext). +*/ +void wxTrace(const wxString& fmt, ... ); + +/** + @b NB: This macro is now obsolete, replaced by @ref overview_logfunctions "Log + functions". + + Calls wxTrace with printf-style variable argument syntax. Output + is directed to the current output stream (see wxDebugContext). +*/ +#define Include files WXTRACE() /* implementation is private */ + diff --git a/interface/menu.h b/interface/menu.h new file mode 100644 index 0000000000..9e60067721 --- /dev/null +++ b/interface/menu.h @@ -0,0 +1,835 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: menu.h +// Purpose: documentation for wxMenuBar class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMenuBar + @wxheader{menu.h} + + A menu bar is a series of menus accessible from the top of a frame. + + @library{wxcore} + @category{menus} + + @seealso + wxMenu, @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxMenuBar : public wxWindow +{ +public: + //@{ + /** + Construct a menu bar from arrays of menus and titles. + + @param n + The number of menus. + + @param menus + An array of menus. Do not use this array again - it now belongs to the + menu bar. + + @param titles + An array of title strings. Deallocate this array after creating the menu bar. + + @param style + If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). + */ + wxMenuBar(long style = 0); + wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[], + long style = 0); + //@} + + /** + Destructor, destroying the menu bar and removing it from the parent frame (if + any). + */ + ~wxMenuBar(); + + /** + Adds the item to the end of the menu bar. + + @param menu + The menu to add. Do not deallocate this menu after calling Append. + + @param title + The title of the menu. + + @returns @true on success, @false if an error occurred. + + @sa Insert() + */ + bool Append(wxMenu * menu, const wxString& title); + + /** + Checks or unchecks a menu item. + + @param id + The menu item identifier. + + @param check + If @true, checks the menu item, otherwise the item is unchecked. + + @remarks Only use this when the menu bar has been associated with a + frame; otherwise, use the wxMenu equivalent call. + */ + void Check(int id, const bool check); + + /** + Enables or disables (greys out) a menu item. + + @param id + The menu item identifier. + + @param enable + @true to enable the item, @false to disable it. + + @remarks Only use this when the menu bar has been associated with a + frame; otherwise, use the wxMenu equivalent call. + */ + void Enable(int id, const bool enable); + + /** + Enables or disables a whole menu. + + @param pos + The position of the menu, starting from zero. + + @param enable + @true to enable the menu, @false to disable it. + + @remarks Only use this when the menu bar has been associated with a frame. + */ + void EnableTop(int pos, const bool enable); + + /** + Finds the menu item object associated with the given menu item identifier. + + @param id + Menu item identifier. + + @param menu + If not @NULL, menu will get set to the associated menu. + + @returns The found menu item object, or @NULL if one was not found. + */ + wxMenuItem * FindItem(int id, wxMenu menu = @NULL); + + /** + Returns the index of the menu with the given @e title or @c wxNOT_FOUND if no + such menu exists in this menubar. The @e title parameter may specify either + the menu title (with accelerator characters, i.e. @c "File") or just the + menu label (@c "File") indifferently. + */ + int FindMenu(const wxString& title); + + /** + Finds the menu item id for a menu name/menu item string pair. + + @param menuString + Menu title to find. + + @param itemString + Item to find. + + @returns The menu item identifier, or wxNOT_FOUND if none was found. + + @remarks Any special menu codes are stripped out of source and target + strings before matching. + */ + int FindMenuItem(const wxString& menuString, + const wxString& itemString); + + /** + Gets the help string associated with the menu item identifier. + + @param id + The menu item identifier. + + @returns The help string, or the empty string if there was no help string + or the menu item was not found. + + @sa SetHelpString() + */ + wxString GetHelpString(int id); + + /** + Gets the label associated with a menu item. + + @param id + The menu item identifier. + + @returns The menu item label, or the empty string if the item was not + found. + + @remarks Use only after the menubar has been associated with a frame. + */ + wxString GetLabel(int id); + + /** + Returns the label of a top-level menu. Note that the returned string does not + include the accelerator characters which could have been specified in the menu + title string during its construction. + + @param pos + Position of the menu on the menu bar, starting from zero. + + @returns The menu label, or the empty string if the menu was not found. + + @remarks Use only after the menubar has been associated with a frame. + + @sa SetLabelTop() + */ + wxString GetLabelTop(int pos); + + /** + Returns the menu at @e menuIndex (zero-based). + */ + wxMenu* GetMenu(int menuIndex); + + /** + Returns the number of menus in this menubar. + */ + size_t GetMenuCount(); + + /** + Returns the label of a top-level menu. Note that the returned string + includes the accelerator characters that have been specified in the menu + title string during its construction. + + @param pos + Position of the menu on the menu bar, starting from zero. + + @returns The menu label, or the empty string if the menu was not found. + + @remarks Use only after the menubar has been associated with a frame. + + @sa GetMenuLabelText(), SetMenuLabel() + */ + wxString GetMenuLabel(int pos); + + /** + Returns the label of a top-level menu. Note that the returned string does not + include any accelerator characters that may have been specified in the menu + title string during its construction. + + @param pos + Position of the menu on the menu bar, starting from zero. + + @returns The menu label, or the empty string if the menu was not found. + + @remarks Use only after the menubar has been associated with a frame. + + @sa GetMenuLabel(), SetMenuLabel() + */ + wxString GetMenuLabelText(int pos); + + /** + Inserts the menu at the given position into the menu bar. Inserting menu at + position 0 will insert it in the very beginning of it, inserting at position + GetMenuCount() is the same as calling + Append(). + + @param pos + The position of the new menu in the menu bar + + @param menu + The menu to add. wxMenuBar owns the menu and will free it. + + @param title + The title of the menu. + + @returns @true on success, @false if an error occurred. + + @sa Append() + */ + bool Insert(size_t pos, wxMenu * menu, const wxString& title); + + /** + Determines whether an item is checked. + + @param id + The menu item identifier. + + @returns @true if the item was found and is checked, @false otherwise. + */ + bool IsChecked(int id); + + /** + Determines whether an item is enabled. + + @param id + The menu item identifier. + + @returns @true if the item was found and is enabled, @false otherwise. + */ + bool IsEnabled(int id); + + /** + Redraw the menu bar + */ + void Refresh(); + + /** + Removes the menu from the menu bar and returns the menu object - the caller is + responsible for deleting it. This function may be used together with + Insert() to change the menubar + dynamically. + + @sa Replace() + */ + wxMenu * Remove(size_t pos); + + /** + Replaces the menu at the given position with another one. + + @param pos + The position of the new menu in the menu bar + + @param menu + The menu to add. + + @param title + The title of the menu. + + @returns The menu which was previously at position pos. The caller is + responsible for deleting it. + + @sa Insert(), Remove() + */ + wxMenu * Replace(size_t pos, wxMenu * menu, + const wxString& title); + + /** + Sets the help string associated with a menu item. + + @param id + Menu item identifier. + + @param helpString + Help string to associate with the menu item. + + @sa GetHelpString() + */ + void SetHelpString(int id, const wxString& helpString); + + /** + Sets the label of a menu item. + + @param id + Menu item identifier. + + @param label + Menu item label. + + @remarks Use only after the menubar has been associated with a frame. + + @sa GetLabel() + */ + void SetLabel(int id, const wxString& label); + + /** + Sets the label of a top-level menu. + + @param pos + The position of a menu on the menu bar, starting from zero. + + @param label + The menu label. + + @remarks Use only after the menubar has been associated with a frame. + + @sa GetLabelTop() + */ + void SetLabelTop(int pos, const wxString& label); + + /** + Sets the label of a top-level menu. + + @param pos + The position of a menu on the menu bar, starting from zero. + + @param label + The menu label. + + @remarks Use only after the menubar has been associated with a frame. + */ + void SetMenuLabel(int pos, const wxString& label); +}; + + +/** + @class wxMenu + @wxheader{menu.h} + + A menu is a popup (or pull down) list of items, one of which may be + selected before the menu goes away (clicking elsewhere dismisses the + menu). Menus may be used to construct either menu bars or popup menus. + + A menu item has an integer ID associated with it which can be used to + identify the selection, or to change the menu item in some way. A menu item + with a special identifier -1 is a separator item and doesn't have an + associated command but just makes a separator line appear in the menu. + + @b NB: Please note that @e wxID_ABOUT and @e wxID_EXIT are + predefined by wxWidgets and have a special meaning since entries + using these IDs will be taken out of the normal menus under MacOS X + and will be inserted into the system menu (following the appropriate + MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according + to Palm OS Companion guidelines. + + Menu items may be either normal items, check items or radio items. Normal items + don't have any special properties while the check items have a boolean flag + associated to them and they show a checkmark in the menu when the flag is set. + wxWidgets automatically toggles the flag value when the item is clicked and its + value may be retrieved using either wxMenu::IsChecked method + of wxMenu or wxMenuBar itself or by using + wxEvent::IsChecked when you get the menu + notification for the item in question. + + The radio items are similar to the check items except that all the other items + in the same radio group are unchecked when a radio item is checked. The radio + group is formed by a contiguous range of radio items, i.e. it starts at the + first item of this kind and ends with the first item of a different kind (or + the end of the menu). Notice that because the radio groups are defined in terms + of the item positions inserting or removing the items in the menu containing + the radio items risks to not work correctly. Finally note that radio items + are not supported under Motif. + + @library{wxcore} + @category{menus} + + @seealso + wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandlingoverview "Event + handling overview", @ref overview_wxfilehistory "wxFileHistory (most recently used files menu)" +*/ +class wxMenu : public wxEvtHandler +{ +public: + //@{ + /** + Constructs a wxMenu object. + + @param style + If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). + */ + wxMenu(const wxString& title = "", long style = 0); + wxMenu(long style); + //@} + + /** + Destructor, destroying the menu. + + Note: under Motif, a popup menu must have a valid parent (the window + it was last popped up on) when being destroyed. Therefore, make sure + you delete or re-use the popup menu @e before destroying the + parent window. Re-use in this context means popping up the menu on + a different window from last time, which causes an implicit destruction + and recreation of internal data structures. + */ + ~wxMenu(); + + //@{ + /** + Adds a menu item object. This is the most generic variant of Append() method + because it may be used for both items (including separators) and submenus and + because you can also specify various extra properties of a menu item this way, + such as bitmaps and fonts. + + @param id + The menu command identifier. + + @param item + The string to appear on the menu item. + + @param menu + Pull-right submenu. + + @param kind + May be wxITEM_SEPARATOR, wxITEM_NORMAL, + wxITEM_CHECK or wxITEM_RADIO + + @param helpString + An optional help string associated with the item. + By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays + this string in the status line. + + @param menuItem + A menuitem object. It will be owned by the wxMenu object after this function + is called, so do not delete it yourself. + + @remarks This command can be used after the menu has been shown, as well + as on initial creation of a menu or menubar. + + @sa AppendSeparator(), AppendCheckItem(), AppendRadioItem(), + AppendSubMenu(), Insert(), SetLabel(), + GetHelpString(), SetHelpString(), wxMenuItem + */ + wxMenuItem* Append(int id, const wxString& item = "", + const wxString& helpString = "", + wxItemKind kind = wxITEM_NORMAL); + wxMenuItem* Append(int id, const wxString& item, + wxMenu * subMenu, + const wxString& helpString = ""); + wxMenuItem* Append(wxMenuItem* menuItem); + //@} + + /** + Adds a checkable item to the end of the menu. + + @sa Append(), InsertCheckItem() + */ + wxMenuItem* AppendCheckItem(int id, const wxString& item, + const wxString& helpString = ""); + + /** + Adds a radio item to the end of the menu. All consequent radio items form a + group and when an item in the group is checked, all the others are + automatically unchecked. + + @sa Append(), InsertRadioItem() + */ + wxMenuItem* AppendRadioItem(int id, const wxString& item, + const wxString& helpString = ""); + + /** + Adds a separator to the end of the menu. + + @sa Append(), InsertSeparator() + */ + wxMenuItem* AppendSeparator(); + + /** + Adds the given @e submenu to this menu. @e text is the text shown in the + menu for it and @e help is the help string shown in the status bar when the + submenu item is selected. + */ + wxMenuItem * AppendSubMenu(wxMenu * submenu, + const wxString& text, + const wxString& help = wxEmptyString); + + /** + Inserts a break in a menu, causing the next appended item to appear in a new + column. + */ + void Break(); + + /** + Checks or unchecks the menu item. + + @param id + The menu item identifier. + + @param check + If @true, the item will be checked, otherwise it will be unchecked. + + @sa IsChecked() + */ + void Check(int id, const bool check); + + //@{ + /** + Deletes the menu item from the menu. If the item is a submenu, it will + @b not be deleted. Use Destroy() if you want to + delete a submenu. + + @param id + Id of the menu item to be deleted. + + @param item + Menu item to be deleted. + + @sa FindItem(), Destroy(), Remove() + */ + void Delete(int id); + void Delete(wxMenuItem * item); + //@} + + //@{ + /** + Deletes the menu item from the menu. If the item is a submenu, it will + be deleted. Use Remove() if you want to keep the submenu + (for example, to reuse it later). + + @param id + Id of the menu item to be deleted. + + @param item + Menu item to be deleted. + + @sa FindItem(), Deletes(), Remove() + */ + void Destroy(int id); + void Destroy(wxMenuItem * item); + //@} + + /** + Enables or disables (greys out) a menu item. + + @param id + The menu item identifier. + + @param enable + @true to enable the menu item, @false to disable it. + + @sa IsEnabled() + */ + void Enable(int id, const bool enable); + + //@{ + /** + Finds the menu item object associated with the given menu item identifier and, + optionally, the (sub)menu it belongs to. + + @param itemString + Menu item string to find. + + @param id + Menu item identifier. + + @param menu + If the pointer is not @NULL, it will be filled with the item's + parent menu (if the item was found) + + @returns First form: menu item identifier, or wxNOT_FOUND if none is + found. + + @remarks Any special menu codes are stripped out of source and target + strings before matching. + */ + int FindItem(const wxString& itemString); + wxMenuItem * FindItem(int id, wxMenu ** menu = @NULL); + //@} + + /** + Returns the wxMenuItem given a position in the menu. + */ + wxMenuItem* FindItemByPosition(size_t position); + + /** + Returns the help string associated with a menu item. + + @param id + The menu item identifier. + + @returns The help string, or the empty string if there is no help string + or the item was not found. + + @sa SetHelpString(), Append() + */ + wxString GetHelpString(int id); + + /** + Returns a menu item label. + + @param id + The menu item identifier. + + @returns The item label, or the empty string if the item was not found. + + @sa GetLabelText(), SetLabel() + */ + wxString GetLabel(int id); + + /** + Returns a menu item label, without any of the original mnemonics and + accelerators. + + @param id + The menu item identifier. + + @returns The item label, or the empty string if the item was not found. + + @sa GetLabel(), SetLabel() + */ + wxString GetLabelText(int id); + + /** + Returns the number of items in the menu. + */ + size_t GetMenuItemCount(); + + /** + Returns the list of items in the menu. wxMenuItemList is a pseudo-template + list class containing wxMenuItem pointers, see wxList. + */ + wxMenuItemList GetMenuItems(); + + /** + Returns the title of the menu. + + @remarks This is relevant only to popup menus, use + wxMenuBar::GetMenuLabel for the menus in the menubar. + + @sa SetTitle() + */ + wxString GetTitle(); + + //@{ + /** + Inserts the given @e item before the position @e pos. Inserting the item + at position GetMenuItemCount() is the same + as appending it. + + @sa Append(), Prepend() + */ + wxMenuItem* Insert(size_t pos, wxMenuItem * item); + wxMenuItem* Insert(size_t pos, int id, + const wxString& item = "", + const wxString& helpString = "", + wxItemKind kind = wxITEM_NORMAL); + //@} + + /** + Inserts a checkable item at the given position. + + @sa Insert(), AppendCheckItem() + */ + wxMenuItem* InsertCheckItem(size_t pos, int id, + const wxString& item, + const wxString& helpString = ""); + + /** + Inserts a radio item at the given position. + + @sa Insert(), AppendRadioItem() + */ + wxMenuItem* InsertRadioItem(size_t pos, int id, + const wxString& item, + const wxString& helpString = ""); + + /** + Inserts a separator at the given position. + + @sa Insert(), AppendSeparator() + */ + wxMenuItem* InsertSeparator(size_t pos); + + /** + Determines whether a menu item is checked. + + @param id + The menu item identifier. + + @returns @true if the menu item is checked, @false otherwise. + + @sa Check() + */ + bool IsChecked(int id); + + /** + Determines whether a menu item is enabled. + + @param id + The menu item identifier. + + @returns @true if the menu item is enabled, @false otherwise. + + @sa Enable() + */ + bool IsEnabled(int id); + + //@{ + /** + Inserts the given @e item at position 0, i.e. before all the other + existing items. + + @sa Append(), Insert() + */ + wxMenuItem* Prepend(wxMenuItem * item); + wxMenuItem* Prepend(int id, const wxString& item = "", + const wxString& helpString = "", + wxItemKind kind = wxITEM_NORMAL); + //@} + + /** + Inserts a checkable item at position 0. + + @sa Prepend(), AppendCheckItem() + */ + wxMenuItem* PrependCheckItem(int id, const wxString& item, + const wxString& helpString = ""); + + /** + Inserts a radio item at position 0. + + @sa Prepend(), AppendRadioItem() + */ + wxMenuItem* PrependRadioItem(int id, const wxString& item, + const wxString& helpString = ""); + + /** + Inserts a separator at position 0. + + @sa Prepend(), AppendSeparator() + */ + wxMenuItem* PrependSeparator(); + + //@{ + /** + Removes the menu item from the menu but doesn't delete the associated C++ + object. This allows to reuse the same item later by adding it back to the menu + (especially useful with submenus). + + @param id + The identifier of the menu item to remove. + + @param item + The menu item to remove. + + @returns The item which was detached from the menu. + */ + wxMenuItem * Remove(int id); + wxMenuItem * Remove(wxMenuItem * item); + //@} + + /** + Sets an item's help string. + + @param id + The menu item identifier. + + @param helpString + The help string to set. + + @sa GetHelpString() + */ + void SetHelpString(int id, const wxString& helpString); + + /** + Sets the label of a menu item. + + @param id + The menu item identifier. + + @param label + The menu item label to set. + + @sa Append(), GetLabel() + */ + void SetLabel(int id, const wxString& label); + + /** + Sets the title of the menu. + + @param title + The title to set. + + @remarks This is relevant only to popup menus, use + wxMenuBar::SetLabelTop for the menus in the menubar. + + @sa GetTitle() + */ + void SetTitle(const wxString& title); + + /** + Sends events to @e source (or owning window if @NULL) to update the + menu UI. This is called just before the menu is popped up with + wxWindow::PopupMenu, but + the application may call it at other times if required. + */ + void UpdateUI(wxEvtHandler* source = @NULL); +}; diff --git a/interface/menuitem.h b/interface/menuitem.h new file mode 100644 index 0000000000..d57a6df054 --- /dev/null +++ b/interface/menuitem.h @@ -0,0 +1,296 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: menuitem.h +// Purpose: documentation for wxMenuItem class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMenuItem + @wxheader{menuitem.h} + + A menu item represents an item in a menu. Note that you usually don't have to + deal with it directly as wxMenu methods usually construct an + object of this class for you. + + Also please note that the methods related to fonts and bitmaps are currently + only implemented for Windows and GTK+. + + @library{wxcore} + @category{menus} + + @seealso + wxMenuBar, wxMenu +*/ +class wxMenuItem : public wxObject +{ +public: + /** + Constructs a wxMenuItem object. + + Menu items can be standard, or "stock menu items'', or custom. For the + standard menu items (such as commands to open a file, exit the program and so + on, see @ref overview_stockitems "stock items" for the full list) it is enough + to + specify just the stock ID and leave @e text and @e helpString empty. In + fact, leaving at least @e text empty for the stock menu items is strongly + recommended as they will have appearance and keyboard interface (including + standard accelerators) familiar to the user. + + For the custom (non-stock) menu items, @e text must be specified and while + @e helpString may be left empty, it's recommended to pass the item + description (which is automatically shown by the library in the status bar when + the menu item is selected) in this parameter. + + Finally note that you can e.g. use a stock menu label without using its stock + help string: + that is, stock properties are set independently one from the other. + + @param parentMenu + Menu that the menu item belongs to. + + @param id + Identifier for this menu item, or wxID_SEPARATOR to indicate a separator. + + @param text + Text for the menu item, as shown on the menu. An accelerator + key can be specified using the ampersand '' character. In order to embed an + ampersand character in the menu item text, the ampersand must be doubled. + + @param helpString + Optional help string that will be shown on the status bar. + + @param kind + May be wxITEM_SEPARATOR, wxITEM_NORMAL, + wxITEM_CHECK or wxITEM_RADIO + + @param subMenu + If non-@NULL, indicates that the menu item is a submenu. + */ + wxMenuItem(wxMenu* parentMenu = @NULL, int id = wxID_SEPARATOR, + const wxString& text = "", + const wxString& helpString = "", + wxItemKind kind = wxITEM_NORMAL, + wxMenu* subMenu = @NULL); + + /** + Destructor. + */ + ~wxMenuItem(); + + /** + Checks or unchecks the menu item. + + Note that this only works when the item is already appended to a menu. + */ + void Check(bool check = @true); + + /** + Enables or disables the menu item. + */ + void Enable(bool enable = @true); + + /** + Returns the background colour associated with the menu item (Windows only). + */ + wxColour GetBackgroundColour(); + + /** + Returns the checked or unchecked bitmap (Windows only). + */ + wxBitmap GetBitmap(bool checked = @true); + + /** + Returns the font associated with the menu item (Windows only). + */ + wxFont GetFont(); + + /** + Returns the help string associated with the menu item. + */ + wxString GetHelp(); + + /** + Returns the menu item identifier. + */ + int GetId(); + + /** + Returns the text associated with the menu item including any accelerator + characters that were passed to the constructor or SetItemLabel. + + @sa GetItemLabelText(), GetLabelText() + */ + wxString GetItemLabel(); + + /** + Returns the text associated with the menu item, without any accelerator + characters. + + @sa GetItemLabel(), GetLabelText() + */ + wxString GetItemLabelText(); + + /** + Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, + @c wxITEM_CHECK or @c wxITEM_RADIO. + */ + wxItemKind GetKind(); + + /** + Returns the text associated with the menu item without any accelerator + characters it might contain. + + This function is deprecated in favour of GetItemLabelText(). + + @sa GetText(), GetLabelFromText() + */ + wxString GetLabel(); + + /** + Strips all accelerator characters and mnemonics from the given @e text. + For example, + will return just @c "Hello". + + This function is deprecated; please use GetLabelText() instead. + + @sa GetText(), GetLabel() + */ + static wxString GetLabelFromText(const wxString& text); + + /** + Strips all accelerator characters and mnemonics from the given @e text. + For example, + will return just @c "Hello". + + @sa GetItemLabelText(), GetItemLabel() + */ + static wxString GetLabelText(const wxString& text); + + /** + Gets the width of the menu item checkmark bitmap (Windows only). + */ + int GetMarginWidth(); + + /** + Returns the menu this menu item is in, or @NULL if this menu item is not + attached. + */ + wxMenu* GetMenu(); + + /** + Returns the text associated with the menu item. + + @b NB: this function is deprecated, please use + GetItemLabel() or GetItemLabelText() + instead. + */ + wxString GetName(); + + /** + Returns the submenu associated with the menu item, or @NULL if there isn't one. + */ + wxMenu* GetSubMenu(); + + /** + Returns the text associated with the menu item, such as it was passed to the + wxMenuItem constructor, i.e. with any accelerator characters it may contain. + + This function is deprecated in favour of GetItemLabel(). + + @sa GetLabel(), GetLabelFromText() + */ + wxString GetText(); + + /** + Returns the text colour associated with the menu item (Windows only). + */ + wxColour GetTextColour(); + + /** + Returns @true if the item is checkable. + */ + bool IsCheckable(); + + /** + Returns @true if the item is checked. + */ + bool IsChecked(); + + /** + Returns @true if the item is enabled. + */ + bool IsEnabled(); + + /** + Returns @true if the item is a separator. + */ + bool IsSeparator(); + + /** + Returns @true if the item is a submenu. + */ + bool IsSubMenu(); + + /** + Sets the background colour associated with the menu item (Windows only). + */ + void SetBackgroundColour(const wxColour& colour); + + /** + Sets the bitmap for the menu item (Windows and GTK+ only). It is + equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap). + */ + void SetBitmap(const wxBitmap& bmp); + + /** + Sets the checked/unchecked bitmaps for the menu item (Windows only). The first + bitmap + is also used as the single bitmap for uncheckable menu items. + */ + void SetBitmaps(const wxBitmap& checked, + const wxBitmap& unchecked = wxNullBitmap); + + /** + Sets the font associated with the menu item (Windows only). + */ + void SetFont(const wxFont& font); + + /** + Sets the help string. + */ + void SetHelp(const wxString& helpString); + + /** + Sets the label associated with the menu item. + */ + void SetItemLabel(const wxString& label); + + /** + Sets the width of the menu item checkmark bitmap (Windows only). + */ + void SetMarginWidth(int width); + + /** + Sets the parent menu which will contain this menu item. + */ + void SetMenu(const wxMenu* menu); + + /** + Sets the submenu of this menu item. + */ + void SetSubMenu(const wxMenu* menu); + + /** + Sets the text associated with the menu item. + + This function is deprecated in favour of SetItemLabel(). + */ + void SetText(const wxString& text); + + /** + Sets the text colour associated with the menu item (Windows only). + */ + void SetTextColour(const wxColour& colour); +}; diff --git a/interface/metafile.h b/interface/metafile.h new file mode 100644 index 0000000000..7ce2472338 --- /dev/null +++ b/interface/metafile.h @@ -0,0 +1,151 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: metafile.h +// Purpose: documentation for wxMetafileDC class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMetafileDC + @wxheader{metafile.h} + + This is a type of device context that allows a metafile object to be + created (Windows only), and has most of the characteristics of a normal + @b wxDC. The wxMetafileDC::Close member must be called after drawing into the + device context, to return a metafile. The only purpose for this at + present is to allow the metafile to be copied to the clipboard (see wxMetafile). + + Adding metafile capability to an application should be easy if you + already write to a wxDC; simply pass the wxMetafileDC to your drawing + function instead. You may wish to conditionally compile this code so it + is not compiled under X (although no harm will result if you leave it + in). + + Note that a metafile saved to disk is in standard Windows metafile format, + and cannot be imported into most applications. To make it importable, + call the function ::wxMakeMetafilePlaceable after + closing your disk-based metafile device context. + + @library{wxcore} + @category{dc} + + @seealso + wxMetafile, wxDC +*/ +class wxMetafileDC : public wxDC +{ +public: + /** + Constructor. If no filename is passed, the metafile is created + in memory. + */ + wxMetafileDC(const wxString& filename = ""); + + /** + Destructor. + */ + ~wxMetafileDC(); + + /** + This must be called after the device context is finished with. A + metafile is returned, and ownership of it passes to the calling + application (so it should be destroyed explicitly). + */ + wxMetafile * Close(); +}; + + +/** + @class wxMetafile + @wxheader{metafile.h} + + A @b wxMetafile represents the MS Windows metafile object, so metafile + operations have no effect in X. In wxWidgets, only sufficient functionality + has been provided for copying a graphic to the clipboard; this may be extended + in a future version. Presently, the only way of creating a metafile + is to use a wxMetafileDC. + + @library{wxcore} + @category{FIXME} + + @seealso + wxMetafileDC +*/ +class wxMetafile : public wxObject +{ +public: + /** + Constructor. If a filename is given, the Windows disk metafile is + read in. Check whether this was performed successfully by + using the @ref isok() wxMetafile:IsOk member. + */ + wxMetafile(const wxString& filename = ""); + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxMetafile(); + + /** + Returns @true if the metafile is valid. + */ +#define bool Ok() /* implementation is private */ + + /** + Plays the metafile into the given device context, returning + @true if successful. + */ + bool Play(wxDC * dc); + + /** + Passes the metafile data to the clipboard. The metafile can no longer be + used for anything, but the wxMetafile object must still be destroyed by + the application. + + Below is a example of metafile, metafile device context and clipboard use + from the @c hello.cpp example. Note the way the metafile dimensions + are passed to the clipboard, making use of the device context's ability + to keep track of the maximum extent of drawing commands. + */ + bool SetClipboard(int width = 0, int height = 0); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Given a filename for an existing, valid metafile (as constructed using + wxMetafileDC) + makes it into a placeable metafile by prepending a header containing the given + bounding box. The bounding box may be obtained from a device context after + drawing + into it, using the functions wxDC::MinX, wxDC::MinY, wxDC::MaxX and wxDC::MaxY. + + In addition to adding the placeable metafile header, this function adds + the equivalent of the following code to the start of the metafile data: + @code + SetMapMode(dc, MM_ANISOTROPIC); + SetWindowOrg(dc, minX, minY); + SetWindowExt(dc, maxX - minX, maxY - minY); + @endcode + + This simulates the wxMM_TEXT mapping mode, which wxWidgets assumes. + + Placeable metafiles may be imported by many Windows applications, and can be + used in RTF (Rich Text Format) files. + + @e scale allows the specification of scale for the metafile. + + This function is only available under Windows. +*/ +bool wxMakeMetafilePlaceable(const wxString& filename, int minX, + int minY, + int maxX, + int maxY, + float scale=1.0); + diff --git a/interface/mimetype.h b/interface/mimetype.h new file mode 100644 index 0000000000..86689aacef --- /dev/null +++ b/interface/mimetype.h @@ -0,0 +1,366 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: mimetype.h +// Purpose: documentation for wxMimeTypesManager class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMimeTypesManager + @wxheader{mimetype.h} + + This class allows the application to retrieve the information about all known + MIME types from a system-specific location and the filename extensions to the + MIME types and vice versa. After initialization the functions + wxMimeTypesManager::GetFileTypeFromMimeType + and wxMimeTypesManager::GetFileTypeFromExtension + may be called: they will return a wxFileType object which + may be further queried for file description, icon and other attributes. + + @b Windows: MIME type information is stored in the registry and no additional + initialization is needed. + + @b Unix: MIME type information is stored in the files mailcap and mime.types + (system-wide) and .mailcap and .mime.types in the current user's home directory: + all of these files are searched for and loaded if found by default. However, + additional functions + wxMimeTypesManager::ReadMailcap and + wxMimeTypesManager::ReadMimeTypes are + provided to load additional files. + + If GNOME or KDE desktop environment is installed, then wxMimeTypesManager + gathers MIME information from respective files (e.g. .kdelnk files under KDE). + + NB: Currently, wxMimeTypesManager is limited to reading MIME type information + but it will support modifying it as well in future versions. + + @library{wxbase} + @category{misc} + + @seealso + wxFileType +*/ +class wxMimeTypesManager +{ +public: + /** + Constructor puts the object in the "working" state, no additional initialization + are needed - but @ref init() ReadXXX may be used to load + additional mailcap/mime.types files. + */ + wxMimeTypesManager(); + + /** + Destructor is not virtual, so this class should not be derived from. + */ + ~wxMimeTypesManager(); + + /** + This function may be used to provide hard-wired fallbacks for the MIME types + and extensions that might not be present in the system MIME database. + + Please see the typetest sample for an example of using it. + */ + void AddFallbacks(const wxFileTypeInfo * fallbacks); + + /** + NB: You won't normally need to use more than one wxMimeTypesManager object in a + program. + + @ref ctor() wxMimeTypesManager + + @ref dtor() ~wxMimeTypesManager + */ + + + /** + Gather information about the files with given extension and return the + corresponding wxFileType object or @NULL if the extension + is unknown. + + The @e extension parameter may have, or not, the leading dot, if it has it, + it is stripped automatically. It must not however be empty. + */ + wxFileType* GetFileTypeFromExtension(const wxString& extension); + + /** + Gather information about the files with given MIME type and return the + corresponding wxFileType object or @NULL if the MIME type + is unknown. + */ + wxFileType* GetFileTypeFromMimeType(const wxString& mimeType); + + /** + All of these functions are static (i.e. don't need a wxMimeTypesManager object + to call them) and provide some useful operations for string representations of + MIME types. Their usage is recommended instead of directly working with MIME + types using wxString functions. + + IsOfType() + */ + + + /** + @b Unix: These functions may be used to load additional files (except for the + default ones which are loaded automatically) containing MIME + information in either mailcap(5) or mime.types(5) format. + + ReadMailcap() + + ReadMimeTypes() + + AddFallbacks() + */ + + + /** + This function returns @true if either the given @e mimeType is exactly the + same as @e wildcard or if it has the same category and the subtype of + @e wildcard is '*'. Note that the '*' wildcard is not allowed in + @e mimeType itself. + + The comparison don by this function is case insensitive so it is not + necessary to convert the strings to the same case before calling it. + */ + bool IsOfType(const wxString& mimeType, const wxString& wildcard); + + /** + These functions are the heart of this class: they allow to find a @ref + overview_wxfiletype "file type" object + from either file extension or MIME type. + If the function is successful, it returns a pointer to the wxFileType object + which @b must be deleted by the caller, otherwise @NULL will be returned. + + GetFileTypeFromMimeType() + + GetFileTypeFromExtension() + */ + + + /** + Load additional file containing information about MIME types and associated + information in mailcap format. See metamail(1) and mailcap(5) for more + information. + + @e fallback parameter may be used to load additional mailcap files without + overriding the settings found in the standard files: normally, entries from + files loaded with ReadMailcap will override the entries from files loaded + previously (and the standard ones are loaded in the very beginning), but this + will not happen if this parameter is set to @true (default is @false). + + The return value is @true if there were no errors in the file or @false + otherwise. + */ + bool ReadMailcap(const wxString& filename, bool fallback = @false); + + /** + Load additional file containing information about MIME types and associated + information in mime.types file format. See metamail(1) and mailcap(5) for more + information. + + The return value is @true if there were no errors in the file or @false + otherwise. + */ + bool ReadMimeTypes(const wxString& filename); +}; + + +/** + @class wxFileType + @wxheader{mimetype.h} + + This class holds information about a given @e file type. File type is the same + as + MIME type under Unix, but under Windows it corresponds more to an extension than + to MIME type (in fact, several extensions may correspond to a file type). This + object may be created in several different ways: the program might know the file + extension and wish to find out the corresponding MIME type or, conversely, it + might want to find the right extension for the file to which it writes the + contents of given MIME type. Depending on how it was created some fields may be + unknown so the return value of all the accessors @b must be checked: @false + will be returned if the corresponding information couldn't be found. + + The objects of this class are never created by the application code but are + returned by wxMimeTypesManager::GetFileTypeFromMimeType and + wxMimeTypesManager::GetFileTypeFromExtension methods. + But it is your responsibility to delete the returned pointer when you're done + with it! + + A brief reminder about what the MIME types are (see the RFC 1341 for more + information): basically, it is just a pair category/type (for example, + "text/plain") where the category is a basic indication of what a file is. + Examples of categories are "application", "image", "text", "binary", and + type is a precise definition of the document format: "plain" in the example + above means just ASCII text without any formatting, while "text/html" is the + HTML document source. + + A MIME type may have one or more associated extensions: "text/plain" will + typically correspond to the extension ".txt", but may as well be associated with + ".ini" or ".conf". + + @library{wxbase} + @category{FIXME} + + @seealso + wxMimeTypesManager +*/ +class wxFileType +{ +public: + /** + The default constructor is private because you should never create objects of + this type: they are only returned by wxMimeTypesManager methods. + */ + wxFileType(); + + /** + The destructor of this class is not virtual, so it should not be derived from. + */ + ~wxFileType(); + + /** + This function is primarily intended for GetOpenCommand and GetPrintCommand + usage but may be also used by the application directly if, for example, you want + to use some non-default command to open the file. + + The function replaces all occurrences of + + + format specification + + + with + + %s + + + the full file name + + %t + + + the MIME type + + %{param} + + + the value of the parameter @e param + + using the MessageParameters object you pass to it. + + If there is no '%s' in the command string (and the string is not empty), it is + assumed that the command reads the data on stdin and so the effect is the same + as " %s" were appended to the string. + + Unlike all other functions of this class, there is no error return for this + function. + */ + static wxString ExpandCommand(const wxString& command, + MessageParameters& params); + + /** + If the function returns @true, the string pointed to by @e desc is filled + with a brief description for this file type: for example, "text document" for + the "text/plain" MIME type. + */ + bool GetDescription(wxString* desc); + + /** + If the function returns @true, the array @e extensions is filled + with all extensions associated with this file type: for example, it may + contain the following two elements for the MIME type "text/html" (notice the + absence of the leading dot): "html" and "htm". + + @b Windows: This function is currently not implemented: there is no + (efficient) way to retrieve associated extensions from the given MIME type on + this platform, so it will only return @true if the wxFileType object was + created + by wxMimeTypesManager::GetFileTypeFromExtension + function in the first place. + */ + bool GetExtensions(wxArrayString& extensions); + + /** + If the function returns @true, the @c iconLoc is filled with the + location of the icon for this MIME type. A wxIcon may be + created from @e iconLoc later. + + @b Windows: The function returns the icon shown by Explorer for the files of + the specified type. + + @b Mac: This function is not implemented and always returns @false. + + @b Unix: MIME manager gathers information about icons from GNOME + and KDE settings and thus GetIcon's success depends on availability + of these desktop environments. + */ + bool GetIcon(wxIconLocation * iconLoc); + + /** + If the function returns @true, the string pointed to by @e mimeType is filled + with full MIME type specification for this file type: for example, "text/plain". + */ + bool GetMimeType(wxString* mimeType); + + /** + Same as GetMimeType() but returns array of MIME + types. This array will contain only one item in most cases but sometimes, + notably under Unix with KDE, may contain more MIME types. This happens when + one file extension is mapped to different MIME types by KDE, mailcap and + mime.types. + */ + bool GetMimeType(wxArrayString& mimeTypes); + + //@{ + /** + With the first version of this method, if the @true is returned, the + string pointed to by @e command is filled with the command which must be + executed (see wxExecute) in order to open the file of the + given type. In this case, the name of the file as well as any other parameters + is retrieved from MessageParameters() + class. + + In the second case, only the filename is specified and the command to be used + to open this kind of file is returned directly. An empty string is returned to + indicate that an error occurred (typically meaning that there is no standard way + to open this kind of files). + */ + bool GetOpenCommand(wxString* command, + MessageParameters& params); + wxString GetOpenCommand(const wxString& filename); + //@} + + /** + If the function returns @true, the string pointed to by @e command is filled + with the command which must be executed (see wxExecute) in + order to print the file of the given type. The name of the file is + retrieved from MessageParameters() class. + */ + bool GetPrintCommand(wxString* command, + MessageParameters& params); + + /** + One of the most common usages of MIME is to encode an e-mail message. The MIME + type of the encoded message is an example of a @e message parameter. These + parameters are found in the message headers ("Content-XXX"). At the very least, + they must specify the MIME type and the version of MIME used, but almost always + they provide additional information about the message such as the original file + name or the charset (for the text documents). + + These parameters may be useful to the program used to open, edit, view or print + the message, so, for example, an e-mail client program will have to pass them to + this program. Because wxFileType itself can not know about these parameters, + it uses MessageParameters class to query them. The default implementation only + requires the caller to provide the file name (always used by the program to be + called - it must know which file to open) and the MIME type and supposes that + there are no other parameters. If you wish to supply additional parameters, you + must derive your own class from MessageParameters and override GetParamValue() + function, for example: + Now you only need to create an object of this class and pass it to, for example, + GetOpenCommand() like this: + @b Windows: As only the file name is used by the program associated with the + given extension anyhow (but no other message parameters), there is no need to + ever derive from MessageParameters class for a Windows-only program. + */ +}; diff --git a/interface/minifram.h b/interface/minifram.h new file mode 100644 index 0000000000..70c9cfa3f5 --- /dev/null +++ b/interface/minifram.h @@ -0,0 +1,116 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: minifram.h +// Purpose: documentation for wxMiniFrame class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMiniFrame + @wxheader{minifram.h} + + A miniframe is a frame with a small title bar. It is suitable for floating + toolbars that must not + take up too much screen area. + + An example of mini frame can be seen in the @ref overview_sampledialogs + "dialogs sample" + using the "Mini frame'' command of the "Generic dialogs'' submenu. + + @beginStyleTable + @style{wxICONIZE}: + Display the frame iconized (minimized) (Windows only). + @style{wxCAPTION}: + Puts a caption on the frame. + @style{wxMINIMIZE}: + Identical to wxICONIZE. + @style{wxMINIMIZE_BOX}: + Displays a minimize box on the frame (Windows and Motif only). + @style{wxMAXIMIZE}: + Displays the frame maximized (Windows only). + @style{wxMAXIMIZE_BOX}: + Displays a maximize box on the frame (Windows and Motif only). + @style{wxCLOSE_BOX}: + Displays a close box on the frame. + @style{wxSTAY_ON_TOP}: + Stay on top of other windows (Windows only). + @style{wxSYSTEM_MENU}: + Displays a system menu (Windows and Motif only). + @style{wxTINY_CAPTION_HORIZ}: + This style is obsolete and not used any longer. + @style{wxTINY_CAPTION_VERT}: + This style is obsolete and not used any longer. + @style{wxRESIZE_BORDER}: + Displays a resizeable border around the window. + @endStyleTable + + @library{wxcore} + @category{managedwnd} + + @seealso + wxMDIParentFrame, wxMDIChildFrame, wxFrame, wxDialog +*/ +class wxMiniFrame : public wxFrame +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent. This may be @NULL. If it is non-@NULL, the frame will + always be displayed on top of the parent window on Windows. + + @param id + The window identifier. It may take a value of -1 to indicate a default value. + + @param title + The caption to be displayed on the frame's title bar. + + @param pos + The window position. The value wxDefaultPosition indicates a default position, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param size + The window size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param style + The window style. See wxMiniFrame. + + @param name + The name of the window. This parameter is used to associate a name with the + item, + allowing the application user to set Motif resource values for + individual windows. + + @remarks The frame behaves like a normal frame on non-Windows platforms. + + @sa Create() + */ + wxMiniFrame(); + wxMiniFrame(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAPTION | wxRESIZE_BORDER, + const wxString& name = "frame"); + //@} + + /** + Destructor. Destroys all child windows and menu bar if present. + */ + ~wxMiniFrame(); + + /** + Used in two-step frame construction. See wxMiniFrame() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAPTION | wxRESIZE_BORDER, + const wxString& name = "frame"); +}; diff --git a/interface/module.h b/interface/module.h new file mode 100644 index 0000000000..a579f08498 --- /dev/null +++ b/interface/module.h @@ -0,0 +1,128 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: module.h +// Purpose: documentation for wxModule class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxModule + @wxheader{module.h} + + The module system is a very simple mechanism to allow applications (and parts + of wxWidgets itself) to define initialization and cleanup functions that are + automatically called on wxWidgets startup and exit. + + To define a new kind of module, derive a class from wxModule, override the + wxModule::OnInit and wxModule::OnExit + functions, and add the DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to + header and implementation files (which can be the same file). On + initialization, wxWidgets will find all classes derived from wxModule, create + an instance of each, and call each OnInit function. On exit, wxWidgets will + call the OnExit function for each module instance. + + Note that your module class does not have to be in a header file. + + For example: + + @code + // A module to allow DDE initialization/cleanup + // without calling these functions from app.cpp or from + // the user's application. + class wxDDEModule: public wxModule + { + public: + wxDDEModule() { } + virtual bool OnInit() { wxDDEInitialize(); return @true; }; + virtual void OnExit() { wxDDECleanUp(); }; + + private: + DECLARE_DYNAMIC_CLASS(wxDDEModule) + }; + + IMPLEMENT_DYNAMIC_CLASS(wxDDEModule, wxModule) + + // Another module which uses DDE in its OnInit() + class MyModule: public wxModule + { + public: + MyModule() { AddDependency(CLASSINFO(wxDDEModule)); } + virtual bool OnInit() { ... code using DDE ... } + virtual void OnExit() { ... } + + private: + DECLARE_DYNAMIC_CLASS(MyModule) + }; + + IMPLEMENT_DYNAMIC_CLASS(MyModule, wxModule) + + // Another module which uses DDE in its OnInit() + // but uses a named dependency + class MyModule2: public wxModule + { + public: + MyModule2() { AddDependency("wxDDEModule"); } + virtual bool OnInit() { ... code using DDE ... } + virtual void OnExit() { ... } + + private: + DECLARE_DYNAMIC_CLASS(MyModule2) + }; + + IMPLEMENT_DYNAMIC_CLASS(MyModule2, wxModule) + @endcode + + @library{wxbase} + @category{FIXME} +*/ +class wxModule : public wxObject +{ +public: + /** + Constructs a wxModule object. + */ + wxModule(); + + /** + Destructor. + */ + ~wxModule(); + + //@{ + /** + Call this function from the constructor of the derived class. @e dep must be + the CLASSINFO of a wxModule-derived class and the + corresponding module will be loaded before and unloaded after + this module. + + The second version of this function allows a dependency to be added by + name without access to the class info. This is useful when a module is + declared entirely in a source file and there is no header for the declaration + of the module needed by CLASSINFO, however errors are + not detected until run-time, instead of compile-time, then. + + Note that circular dependencies are detected and result in a fatal error. + + @param dep + The class information object for the dependent module. + + @param classname + The class name of the dependent module. + */ + void AddDependency(wxClassInfo * dep); + void AddDependency(const char * classname); + //@} + + /** + Provide this function with appropriate cleanup for your module. + */ + virtual void OnExit(); + + /** + Provide this function with appropriate initialization for your module. If the + function + returns @false, wxWidgets will exit immediately. + */ + virtual bool OnInit(); +}; diff --git a/interface/msgdlg.h b/interface/msgdlg.h new file mode 100644 index 0000000000..22d7bb3406 --- /dev/null +++ b/interface/msgdlg.h @@ -0,0 +1,239 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msgdlg.h +// Purpose: documentation for wxMessageDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMessageDialog + @wxheader{msgdlg.h} + + This class represents a dialog that shows a single or multi-line message, + with a choice of OK, Yes, No and Cancel buttons. + + @library{wxcore} + @category{cmndlg} + + @seealso + @ref overview_wxmessagedialogoverview "wxMessageDialog overview" +*/ +class wxMessageDialog : public wxDialog +{ +public: + /** + Constructor. Use ShowModal() to show the dialog. + + @param parent + Parent window. + + @param message + Message to show on the dialog. + + @param caption + The dialog caption. + + @param style + A dialog style (bitlist) containing flags chosen from the following: + + + wxOK + + + Show an OK button. + + wxCANCEL + + + Show a Cancel button. + + wxYES_NO + + + Show Yes and No buttons. + + wxYES_DEFAULT + + + Used with wxYES_NO, makes Yes button the default - which is the default + behaviour. + + wxNO_DEFAULT + + + Used with wxYES_NO, makes No button the default. + + wxICON_EXCLAMATION + + + Shows an exclamation mark icon. + + wxICON_HAND + + + Shows an error icon. + + wxICON_ERROR + + + Shows an error icon - the same as wxICON_HAND. + + wxICON_QUESTION + + + Shows a question mark icon. + + wxICON_INFORMATION + + + Shows an information (i) icon. + + wxSTAY_ON_TOP + + + The message box stays on top of all other window, even those of the other + applications (Windows only). + + @param pos + Dialog position. Not Windows. + */ + wxMessageDialog(wxWindow* parent, const wxString& message, + const wxString& caption = "Message box", + long style = wxOK | wxCANCEL, + const wxPoint& pos = wxDefaultPosition); + + /** + Destructor. + */ + ~wxMessageDialog(); + + /** + Sets the extended message for the dialog: this message is usually an extension + of the short message specified in the constructor or set with + SetMessage(). If it is set, the main message + appears highlighted -- if supported -- and this message appears beneath it in + normal font. On the platforms which don't support extended messages, it is + simply appended to the normal message with a new line separating them. + */ + void SetExtendedMessage(const wxString exMsg); + + /** + Sets the message shown by the dialog. + */ + void SetMessage(const wxString msg); + + /** + Overrides the default labels of the OK and Cancel buttons. + + Please see the remarks in + SetYesNoLabels() documentation. + */ + bool SetOKCancelLabels(const wxString ok, const wxString cancel); + + /** + Overrides the default label of the OK button. + + Please see the remarks in + SetYesNoLabels() documentation. + */ + bool SetOKLabel(const wxString ok); + + /** + Overrides the default labels of the Yes, No and Cancel buttons. + + Please see the remarks in + SetYesNoLabels() documentation. + */ + bool SetYesNoCancelLabels(const wxString yes, const wxString no, + const wxString cancel); + + /** + Overrides the default labels of the Yes and No buttons. + + Notice that this function is not currently available on all platforms, so it + may return @false to indicate that the labels couldn't be changed. If it + returns @true (currently only under wxMac), the labels were set successfully. + Typically, if the function was used successfully, the main dialog message may + need to be changed, e.g.: + */ + bool SetYesNoLabels(const wxString yes, const wxString no); + + /** + Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, wxID_NO. + */ + int ShowModal(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + General purpose message dialog. @e style may be a bit list of the + following identifiers: + + wxYES_NO + + + Puts Yes and No buttons on the message box. May be combined with + wxCANCEL. + + wxCANCEL + + + Puts a Cancel button on the message box. May only be combined with + wxYES_NO or wxOK. + + wxOK + + + Puts an Ok button on the message box. May be combined with wxCANCEL. + + wxICON_EXCLAMATION + + + Displays an exclamation mark symbol. + + wxICON_HAND + + + Displays an error symbol. + + wxICON_ERROR + + + Displays an error symbol - the same as wxICON_HAND. + + wxICON_QUESTION + + + Displays a question mark symbol. + + wxICON_INFORMATION + + + Displays an information symbol. + + The return value is one of: wxYES, wxNO, wxCANCEL, wxOK. + + For example: + @code + ... + int answer = wxMessageBox("Quit program?", "Confirm", + wxYES_NO | wxCANCEL, main_frame); + if (answer == wxYES) + main_frame-Close(); + ... + @endcode + + @e message may contain newline characters, in which case the + message will be split into separate lines, to cater for large messages. +*/ +int wxMessageBox(const wxString& message, + const wxString& caption = "Message", + int style = wxOK, + wxWindow * parent = @NULL, + int x = -1, int y = -1); + diff --git a/interface/msgqueue.h b/interface/msgqueue.h new file mode 100644 index 0000000000..43d076c828 --- /dev/null +++ b/interface/msgqueue.h @@ -0,0 +1,75 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msgqueue.h +// Purpose: documentation for wxMessageQueue class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMessageQueueT + @wxheader{msgqueue.h} + + wxMessageQueue allows passing messages between threads. + + This class should be typically used to communicate between the main and worker + threads. The main thread calls wxMessageQueue::Post and + the worker thread calls wxMessageQueue::Receive. + + For this class a message is an object of arbitrary type T. Notice that + often there is a some special message indicating that the thread + should terminate as there is no other way to gracefully shutdown a thread + waiting on the message queue. + + @nolibrary + @category{FIXME} + + @seealso + wxThread +*/ +class wxMessageQueue +{ +public: + /** + Returns @true if the object had been initialized successfully, @false + if an error occurred. + */ +#define bool IsOk() /* implementation is private */ + + /** + Add a message to this queue and signal the threads waiting for messages + (i.e. the threads which called wxMessageQueue::Receive or + wxMessageQueue::ReceiveTimeout). + + This method is safe to call from multiple threads in parallel. + */ + wxMessageQueueError Post(T const& msg); + + /** + Block until a message becomes available in the queue. Waits indefinitely long + or until an error occurs. + + The message is returned in @e msg. + */ + wxMessageQueueError Receive(T& msg); + + /** + Block until a message becomes available in the queue, but no more than + @e timeout milliseconds has elapsed. + + If no message is available after @e timeout milliseconds then returns + @b wxMSGQUEUE_TIMEOUT. + + If @e timeout is 0 then checks for any messages present in the queue + and returns immediately without waiting. + + The message is returned in @e msg. + */ + wxMessageQueueError ReceiveTimeout(long timeout, T& msg); + + /** + Default and only constructor. Use wxMessageQueue::IsOk to check + if the object was successfully initialized. + */ + wxMessageQueue(); +}; diff --git a/interface/mstream.h b/interface/mstream.h new file mode 100644 index 0000000000..c3d0f02f49 --- /dev/null +++ b/interface/mstream.h @@ -0,0 +1,88 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: mstream.h +// Purpose: documentation for wxMemoryOutputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMemoryOutputStream + @wxheader{mstream.h} + + + @library{wxbase} + @category{streams} + + @seealso + wxStreamBuffer +*/ +class wxMemoryOutputStream : public wxOutputStream +{ +public: + /** + If @e data is @NULL, then it will initialize a new empty buffer which will + grow if required. + */ + wxMemoryOutputStream(char * data = @NULL, size_t length = 0); + + /** + Destructor. + */ + ~wxMemoryOutputStream(); + + /** + CopyTo allowed you to transfer data from the internal buffer of + wxMemoryOutputStream to an external buffer. @e len specifies the size of + the buffer. + */ + size_t CopyTo(char * buffer, size_t len); + + /** + Returns the pointer to the stream object used as an internal buffer + for that stream. + */ + wxStreamBuffer * GetOutputStreamBuffer(); +}; + + +/** + @class wxMemoryInputStream + @wxheader{mstream.h} + + + @library{wxbase} + @category{streams} + + @seealso + wxStreamBuffer, wxMemoryOutputStream +*/ +class wxMemoryInputStream : public wxInputStream +{ +public: + //@{ + /** + Creates a new read-only memory stream, initializing it with the + data from the given input stream @e stream. + + The @e len argument specifies the amount of data to read from + the @e stream. Setting it to @e wxInvalidOffset means that + the @e stream is to be read entirely (i.e. till the EOF is reached). + */ + wxMemoryInputStream(const char * data, size_t len); + wxMemoryInputStream(const wxMemoryOutputStream& stream); + wxMemoryInputStream(wxInputStream& stream, + wxFileOffset len = wxInvalidOffset); + //@} + + /** + Destructor. + */ + ~wxMemoryInputStream(); + + /** + Returns the pointer to the stream object used as an internal buffer + for that stream. + */ + wxStreamBuffer * GetInputStreamBuffer(); +}; diff --git a/interface/msw/ole/activex.h b/interface/msw/ole/activex.h new file mode 100644 index 0000000000..09cf99a918 --- /dev/null +++ b/interface/msw/ole/activex.h @@ -0,0 +1,95 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msw/ole/activex.h +// Purpose: documentation for wxActiveXEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxActiveXEvent + @headerfile ole/activex.h wx/msw/ole/activex.h + + An event class for handling activex events passed from + wxActiveXContainer. ActiveX events are basically + a function call with the parameters passed through an array of wxVariants along + with a return value that is a wxVariant itself. What type the parameters or + return value are depends on the context (i.e. what the .idl specifies). + + Note that unlike the third party wxActiveX function names are not supported. + + @library{wxbase} + @category{FIXME} +*/ +class wxActiveXEvent : public wxCommandEvent +{ +public: + /** + Returns the dispatch id of this activex event. This is the numeric value from + the .idl file specified by the id(). + */ + DISPID GetDispatchId(int idx); + + /** + Obtains the number of parameters passed through the activex event. + */ + size_t ParamCount(); + + /** + Obtains the param name of the param number idx specifies as a string. + */ + wxString ParamName(size_t idx); + + /** + Obtains the param type of the param number idx specifies as a string. + */ + wxString ParamType(size_t idx); + + /** + Obtains the actual parameter value specified by idx. + */ + wxVariant operator[](size_t idx); +}; + + +/** + @class wxActiveXContainer + @headerfile ole/activex.h wx/msw/ole/activex.h + + wxActiveXContainer is a host for an activex control on Windows (and + as such is a platform-specific class). Note that the HWND that the class + contains is the actual HWND of the activex control so using dynamic events + and connecting to wxEVT_SIZE, for example, will recieve the actual size + message sent to the control. + + It is somewhat similar to the ATL class CAxWindow in operation. + + The size of the activex control's content is generally gauranteed to be that + of the client size of the parent of this wxActiveXContainer. + + You can also process activex events through wxEVT_ACTIVEX or the + corresponding message map macro EVT_ACTIVEX. + + @library{wxbase} + @category{FIXME} + + @seealso + wxActiveXEvent +*/ +class wxActiveXContainer : public wxControl +{ +public: + /** + Creates this activex container. + + @param parent + parent of this control. Must not be @NULL. + + @param iid + COM IID of pUnk to query. Must be a valid interface to an activex control. + + @param pUnk + Interface of activex control + */ + wxActiveXContainer(wxWindow* parent, REFIID iid, IUnknown* pUnk); +}; diff --git a/interface/msw/ole/automtn.h b/interface/msw/ole/automtn.h new file mode 100644 index 0000000000..8e4a970a49 --- /dev/null +++ b/interface/msw/ole/automtn.h @@ -0,0 +1,206 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msw/ole/automtn.h +// Purpose: documentation for wxAutomationObject class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAutomationObject + @headerfile ole/automtn.h wx/msw/ole/automtn.h + + The @b wxAutomationObject class represents an OLE automation object containing + a single data member, + an IDispatch pointer. It contains a number of functions that make it easy to + perform + automation operations, and set and get properties. The class makes heavy use of + the wxVariant class. + + The usage of these classes is quite close to OLE automation usage in Visual + Basic. The API is + high-level, and the application can specify multiple properties in a single + string. The following example + gets the current Excel instance, and if it exists, makes the active cell bold. + + @code + wxAutomationObject excelObject; + if (excelObject.GetInstance("Excel.Application")) + excelObject.PutProperty("ActiveCell.Font.Bold", @true); + @endcode + + Note that this class obviously works under Windows only. + + @library{wxcore} + @category{misc} + + @seealso + wxVariant +*/ +class wxAutomationObject : public wxObject +{ +public: + /** + Constructor, taking an optional IDispatch pointer which will be released when + the + object is deleted. + */ + wxAutomationObject(WXIDISPATCH* dispatchPtr = @NULL); + + /** + Destructor. If the internal IDispatch pointer is non-null, it will be released. + */ + ~wxAutomationObject(); + + //@{ + /** + Calls an automation method for this object. The first form takes a method name, + number of + arguments, and an array of variants. The second form takes a method name and + zero to six + constant references to variants. Since the variant class has constructors for + the basic + data types, and C++ provides temporary objects automatically, both of the + following lines + are syntactically valid: + + + Note that @e method can contain dot-separated property names, to save the + application + needing to call GetProperty several times using several temporary objects. For + example: + */ + wxVariant CallMethod(const wxString& method, int noArgs, + wxVariant args[]); + wxVariant CallMethod(const wxString& method, ... ); + //@} + + /** + Creates a new object based on the class id, returning @true if the object was + successfully created, + or @false if not. + */ + bool CreateInstance(const wxString& classId); + + /** + Gets the IDispatch pointer. + */ + IDispatch* GetDispatchPtr(); + + /** + Retrieves the current object associated with a class id, and attaches the + IDispatch pointer + to this object. Returns @true if a pointer was successfully retrieved, @false + otherwise. + + Note that this cannot cope with two instances of a given OLE object being + active simultaneously, + such as two copies of Excel running. Which object is referenced cannot + currently be specified. + */ + bool GetInstance(const wxString& classId); + + /** + Retrieves a property from this object, assumed to be a dispatch pointer, and + initialises @e obj with it. + To avoid having to deal with IDispatch pointers directly, use this function in + preference + to GetProperty() when retrieving objects + from other objects. + + Note that an IDispatch pointer is stored as a void* pointer in wxVariant + objects. + + @sa GetProperty() + */ + bool GetObject(wxAutomationObject& obj, const wxString& property, + int noArgs = 0, + wxVariant args[] = @NULL); + + //@{ + /** + Gets a property value from this object. The first form takes a property name, + number of + arguments, and an array of variants. The second form takes a property name and + zero to six + constant references to variants. Since the variant class has constructors for + the basic + data types, and C++ provides temporary objects automatically, both of the + following lines + are syntactically valid: + + + Note that @e property can contain dot-separated property names, to save the + application + needing to call GetProperty several times using several temporary objects. + */ + wxVariant GetProperty(const wxString& property, int noArgs, + wxVariant args[]); + wxVariant GetProperty(const wxString& property, ... ); + //@} + + /** + This function is a low-level implementation that allows access to the IDispatch + Invoke function. + It is not meant to be called directly by the application, but is used by other + convenience functions. + + @param member + The member function or property name. + + @param action + Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, + DISPATCH_METHOD. + + @param retValue + Return value (ignored if there is no return value) + + @param noArgs + Number of arguments in args or ptrArgs. + + @param args + If non-null, contains an array of variants. + + @param ptrArgs + If non-null, contains an array of constant pointers to variants. + + @returns @true if the operation was successful, @false otherwise. + + @remarks Two types of argument array are provided, so that when possible + pointers are used for efficiency. + */ + bool Invoke(const wxString& member, int action, + wxVariant& retValue, int noArgs, + wxVariant args[], + const wxVariant* ptrArgs[] = 0); + + //@{ + /** + Puts a property value into this object. The first form takes a property name, + number of + arguments, and an array of variants. The second form takes a property name and + zero to six + constant references to variants. Since the variant class has constructors for + the basic + data types, and C++ provides temporary objects automatically, both of the + following lines + are syntactically valid: + + + Note that @e property can contain dot-separated property names, to save the + application + needing to call GetProperty several times using several temporary objects. + */ + bool PutProperty(const wxString& property, int noArgs, + wxVariant args[]); + bool PutProperty(const wxString& property, ... ); + //@} + + /** + Sets the IDispatch pointer. This function does not check if there is already an + IDispatch pointer. + + You may need to cast from IDispatch* to WXIDISPATCH* when calling this function. + */ + void SetDispatchPtr(WXIDISPATCH* dispatchPtr); +}; diff --git a/interface/msw/registry.h b/interface/msw/registry.h new file mode 100644 index 0000000000..e06511726a --- /dev/null +++ b/interface/msw/registry.h @@ -0,0 +1,192 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msw/registry.h +// Purpose: documentation for wxRegKey class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRegKey + @headerfile registry.h wx/msw/registry.h + + wxRegKey is a class representing the Windows registry (it is only available + under Windows). One can create, query and delete registry keys using this + class. + + The Windows registry is easy to understand. There are five registry keys, + namely: + + HKEY_CLASSES_ROOT (HKCR) + HKEY_CURRENT_USER (HKCU) + HKEY_LOCAL_MACHINE (HKLM) + HKEY_CURRENT_CONFIG (HKCC) + HKEY_USERS (HKU) + + After creating a key, it can hold a value. The values can be: + + String Value + Binary Value + DWORD Value + Multi String Value + Expandable String Value + + + @library{wxbase} + @category{FIXME} +*/ +class wxRegKey +{ +public: + //@{ + /** + The constructor to set the full name of the key under a previously created + parent. + */ + wxRegKey(); + wxRegKey(const wxString& strKey); + wxRegKey(const wxRegKey& keyParent, const wxString& strKey); + //@} + + /** + Closes the key. + */ + void Close(); + + /** + Creates the key. Will fail if the key already exists and @e bOkIfExists is + @false. + */ + bool Create(bool bOkIfExists = @true); + + /** + Deletes the subkey with all of its subkeys/values recursively. + */ + void DeleteKey(const wxChar * szKey); + + /** + Deletes this key and all of its subkeys and values recursively. + */ + void DeleteSelf(); + + /** + Deletes the named value. + */ + void DeleteValue(const wxChar * szKey); + + /** + Returns @true if the key exists. + */ + static bool Exists(); + + /** + Gets the first key. + */ + bool GetFirstKey(wxString& strKeyName, long& lIndex); + + /** + Gets the first value of this key. + */ + bool GetFirstValue(wxString& strValueName, long& lIndex); + + /** + Gets information about the key. + + @param pnSubKeys + The number of subkeys. + + @param pnMaxKeyLen + The maximum length of the subkey name. + + @param pnValues + The number of values. + + @param pnMaxValueLen + The maximum length of a value. + */ + bool GetKeyInfo(size_t * pnSubKeys, size_t * pnValues, + size_t * pnMaxValueLen); + + /** + Gets the name of the registry key. + */ + wxString GetName(bool bShortPrefix = @true); + + /** + Gets the next key. + */ + bool GetNextKey(wxString& strKeyName, long& lIndex); + + /** + Gets the next key value for this key. + */ + bool GetNextValue(wxString& strValueName, long& lIndex); + + /** + Returns @true if given subkey exists. + */ + bool HasSubKey(const wxChar * szKey); + + /** + Returns @true if any subkeys exist. + */ + bool HasSubKeys(); + + /** + Returns @true if the value exists. + */ + bool HasValue(const wxChar * szValue); + + /** + Returns @true if any values exist. + */ + bool HasValues(); + + /** + Returns @true if this key is empty, nothing under this key. + */ + bool IsEmpty(); + + /** + Returns @true if the key is opened. + */ + bool IsOpened(); + + /** + Explicitly opens the key. This method also allows the key to be opened in + read-only mode by passing @c Read() instead of default + @c Write() parameter. + */ + bool Open(AccessMode mode = Write); + + //@{ + /** + Retrieves the numeric value. + */ + bool QueryValue(const wxChar * szValue, wxString& strValue); + bool QueryValue(const wxChar * szValue, long * plValue); + //@} + + /** + Renames the key. + */ + bool Rename(const wxChar * szNewName); + + /** + Renames a value. + */ + bool RenameValue(const wxChar * szValueOld, + const wxChar * szValueNew); + + //@{ + /** + Sets the given @e szValue which must be numeric, string or binary depending + on the overload used. If the value doesn't exist, it is created. + */ + bool SetValue(const wxChar * szValue, long lValue); + bool SetValue(const wxChar * szValue, + const wxString& strValue); + bool SetValue(const wxChar * szValue, + const wxMemoryBuffer& buf); + //@} +}; diff --git a/interface/notebook.h b/interface/notebook.h new file mode 100644 index 0000000000..78b8dac467 --- /dev/null +++ b/interface/notebook.h @@ -0,0 +1,416 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: notebook.h +// Purpose: documentation for wxNotebookEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxNotebookEvent + @wxheader{notebook.h} + + This class represents the events generated by a notebook control: currently, + there are two of them. The PAGE_CHANGING event is sent before the current + page is changed. It allows the program to examine the current page (which + can be retrieved with + wxNotebookEvent::GetOldSelection) and to veto the page + change by calling wxNotifyEvent::Veto if, for example, the + current values in the controls of the old page are invalid. + + The second event - PAGE_CHANGED - is sent after the page has been changed and + the program cannot veto it any more, it just informs it about the page change. + + To summarize, if the program is interested in validating the page values + before allowing the user to change it, it should process the PAGE_CHANGING + event, otherwise PAGE_CHANGED is probably enough. In any case, it is probably + unnecessary to process both events at once. + + @library{wxcore} + @category{events} + + @seealso + wxNotebook +*/ +class wxNotebookEvent : public wxNotifyEvent +{ +public: + /** + Constructor (used internally by wxWidgets only). + */ + wxNotebookEvent(wxEventType eventType = wxEVT_@NULL, int id = 0, + int sel = -1, + int oldSel = -1); + + /** + Returns the page that was selected before the change, -1 if none was selected. + */ + int GetOldSelection(); + + /** + Returns the currently selected page, or -1 if none was selected. + + @b NB: under Windows, GetSelection() will return the same value as + GetOldSelection() when called from + @c EVT_NOTEBOOK_PAGE_CHANGING handler and not the page which is going to + be selected. Also note that the values of selection and old selection returned + for an event generated in response to a call to + wxNotebook::SetSelection shouldn't be trusted + as they are currently inconsistent under different platforms (but in this case + you presumably don't need them anyhow as you already have the corresponding + information). + */ + int GetSelection(); + + /** + Sets the id of the page selected before the change. + */ + void SetOldSelection(int page); + + /** + Sets the selection member variable. + */ + void SetSelection(int page); +}; + + +/** + @class wxNotebook + @wxheader{notebook.h} + + This class represents a notebook control, which manages multiple windows with + associated tabs. + + To use the class, create a wxNotebook object and call wxNotebook::AddPage or + wxNotebook::InsertPage, + passing a window to be used as the page. Do not explicitly delete the window + for a page that is currently + managed by wxNotebook. + + @b wxNotebookPage is a typedef for wxWindow. + + @beginStyleTable + @style{wxNB_TOP}: + Place tabs on the top side. + @style{wxNB_LEFT}: + Place tabs on the left side. + @style{wxNB_RIGHT}: + Place tabs on the right side. + @style{wxNB_BOTTOM}: + Place tabs under instead of above the notebook pages. + @style{wxNB_FIXEDWIDTH}: + (Windows only) All tabs will have same width. + @style{wxNB_MULTILINE}: + (Windows only) There can be several rows of tabs. + @style{wxNB_NOPAGETHEME}: + (Windows only) Display a solid colour on notebook pages, and not a + gradient, which can reduce performance. + @style{wxNB_FLAT}: + (Windows CE only) Show tabs in a flat style. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @seealso + wxBookCtrl, wxNotebookEvent, wxImageList, @ref overview_samplenotebook + "notebook sample" +*/ +class wxNotebook : public wxBookCtrl overview +{ +public: + //@{ + /** + Constructs a notebook control. + + Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN + window style. + + @param parent + The parent window. Must be non-@NULL. + + @param id + The window identifier. + + @param pos + The window position. + + @param size + The window size. + + @param style + The window style. See wxNotebook. + + @param name + The name of the control (used only under Motif). + */ + wxNotebook(); + wxNotebook(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxNotebookNameStr); + //@} + + /** + Destroys the wxNotebook object. + */ + ~wxNotebook(); + + /** + Adds a new page. + + The call to this function may generate the page changing events. + + @param page + Specifies the new page. + + @param text + Specifies the text for the new page. + + @param select + Specifies whether the page should be selected. + + @param imageId + Specifies the optional image index for the new page. + + @returns @true if successful, @false otherwise. + + @remarks Do not delete the page, it will be deleted by the notebook. + + @sa InsertPage() + */ + bool AddPage(wxNotebookPage* page, const wxString& text, + bool select = @false, + int imageId = -1); + + /** + Cycles through the tabs. + + The call to this function generates the page changing events. + */ + void AdvanceSelection(bool forward = @true); + + /** + Sets the image list for the page control and takes ownership of + the list. + + @sa wxImageList, SetImageList() + */ + void AssignImageList(wxImageList* imageList); + + /** + Changes the selection for the given page, returning the previous selection. + + The call to this function does not generate the page changing events. + This is the only difference with SetSelection(). + See @ref overview_progevent "this topic" for more info. + */ + int ChangeSelection(size_t page); + + /** + Creates a notebook control. See wxNotebook() for a description + of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size, long style = 0, + const wxString& name = wxNotebookNameStr); + + /** + Deletes all pages. + */ + bool DeleteAllPages(); + + /** + Deletes the specified page, and the associated window. + + The call to this function generates the page changing events. + */ + bool DeletePage(size_t page); + + /** + Returns the currently selected notebook page or @NULL. + */ + wxWindow * GetCurrentPage(); + + /** + Returns the associated image list. + + @sa wxImageList, SetImageList() + */ + wxImageList* GetImageList(); + + /** + Returns the window at the given page position. + */ + wxNotebookPage* GetPage(size_t page); + + /** + Returns the number of pages in the notebook control. + */ + size_t GetPageCount(); + + /** + Returns the image index for the given page. + */ + int GetPageImage(size_t nPage); + + /** + Returns the string for the given page. + */ + wxString GetPageText(size_t nPage); + + /** + Returns the number of rows in the notebook control. + */ + int GetRowCount(); + + /** + Returns the currently selected page, or -1 if none was selected. + + Note that this method may return either the previously or newly selected page + when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler depending on + the platform and so + wxNotebookEvent::GetSelection should be + used instead in this case. + */ + int GetSelection(); + + /** + If running under Windows and themes are enabled for the application, this + function + returns a suitable colour for painting the background of a notebook page, and + can be passed + to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned. + */ + wxColour GetThemeBackgroundColour(); + + /** + Returns the index of the tab at the specified position or @c wxNOT_FOUND + if none. If @e flags parameter is non-@NULL, the position of the point + inside the tab is returned as well. + + @param pt + Specifies the point for the hit test. + + @param flags + Return value for detailed information. One of the following values: + + wxBK_HITTEST_NOWHERE + + + There was no tab under this point. + + wxBK_HITTEST_ONICON + + + The point was over an icon (currently wxMSW only). + + wxBK_HITTEST_ONLABEL + + + The point was over a label (currently wxMSW only). + + wxBK_HITTEST_ONITEM + + + The point was over an item, but not on the label or icon. + + wxBK_HITTEST_ONPAGE + + + The point was over a currently selected page, not over any tab. Note that this + flag is present only if wxNOT_FOUND is returned. + + @returns Returns the zero-based tab index or wxNOT_FOUND if there is no + tab is at the specified position. + */ + int HitTest(const wxPoint& pt, long flags = @NULL); + + /** + Inserts a new page at the specified position. + + @param index + Specifies the position for the new page. + + @param page + Specifies the new page. + + @param text + Specifies the text for the new page. + + @param select + Specifies whether the page should be selected. + + @param imageId + Specifies the optional image index for the new page. + + @returns @true if successful, @false otherwise. + + @remarks Do not delete the page, it will be deleted by the notebook. + + @sa AddPage() + */ + bool InsertPage(size_t index, wxNotebookPage* page, + const wxString& text, + bool select = @false, + int imageId = -1); + + /** + An event handler function, called when the page selection is changed. + + @sa wxNotebookEvent + */ + void OnSelChange(wxNotebookEvent& event); + + /** + Deletes the specified page, without deleting the associated window. + */ + bool RemovePage(size_t page); + + /** + Sets the image list for the page control. It does not take + ownership of the image list, you must delete it yourself. + + @sa wxImageList, AssignImageList() + */ + void SetImageList(wxImageList* imageList); + + /** + Sets the amount of space around each page's icon and label, in pixels. + + @b NB: The vertical padding cannot be changed in wxGTK. + */ + void SetPadding(const wxSize& padding); + + /** + Sets the image index for the given page. @e image is an index into + the image list which was set with SetImageList(). + */ + bool SetPageImage(size_t page, int image); + + /** + Sets the width and height of the pages. + + @b NB: This method is currently not implemented for wxGTK. + */ + void SetPageSize(const wxSize& size); + + /** + Sets the text for the given page. + */ + bool SetPageText(size_t page, const wxString& text); + + /** + Sets the selection for the given page, returning the previous selection. + + The call to this function generates the page changing events. + + This function is deprecated and should not be used in new code. Please use the + ChangeSelection() function instead. + + @sa GetSelection() + */ + int SetSelection(size_t page); +}; diff --git a/interface/notifmsg.h b/interface/notifmsg.h new file mode 100644 index 0000000000..78a3c0ca0b --- /dev/null +++ b/interface/notifmsg.h @@ -0,0 +1,93 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: notifmsg.h +// Purpose: documentation for wxNotificationMessage class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxNotificationMessage + @wxheader{notifmsg.h} + + This class allows to show the user a message non intrusively. Currently it is + implemented natively only for the Maemo platform and uses (non-modal) dialogs + for the display of the notifications under the other platforms but it will be + extended to use the platform-specific notifications in the other ports in the + future. + + Notice that this class is not a window and so doesn't derive from wxWindow. + + @library{wxbase} + @category{FIXME} +*/ +class wxNotificationMessage : public wxEvtHandler +{ +public: + //@{ + /** + , @b wxWindow*@e parent = @NULL, @b int@e flags = @c wxICON_INFORMATION) + + Create a notification object with the given attributes. + + See SetTitle(), + SetMessage(), + SetParent() and + SetFlags() for the description of the + corresponding parameters. + */ + wxNotificationMessage(); + wxNotificationMessage(const wxString& title); + //@} + + /** + Hides the notification. + + Returns @true if it was hidden or @false if it couldn't be done (e.g. on + some + systems automatically hidden notifications can't be hidden manually) + */ + bool Close(); + + /** + This parameter can be currently used to specify the icon to show in the + notification. Valid values are @c wxICON_INFORMATION, + @c wxICON_WARNING and @c wxICON_ERROR (notice that + @c wxICON_QUESTION is not allowed here). + + Some implementations of this class may not support the icons. + */ + void SetFlags(int flags); + + /** + Set the main text of the notification. This should be a more detailed + description than the title but still limited to reasonable length (not more + than 256 characters). + */ + void SetMessage(const wxString& message); + + /** + Set the parent for this notification: the notification will be associated with + the top level parent of this window or, if this method is not called, with the + main application window by default + */ + void SetParent(wxWindow* parent); + + /** + Set the title, it must be a concise string (not more than 64 characters), use + SetMessage() to give the user more + details. + */ + void SetTitle(const wxString& title); + + /** + Show the notification to the user and hides it after timeout seconds + pass. Special values @c Timeout_Auto and @c Timeout_Never can be + used here, notice that you shouldn't rely on @e timeout being exactly + respected because the current platform may only support default timeout value + and also because the user may be able to close the notification. + + Returns @false if an error occurred. + */ + bool Show(int timeout = Timeout_Auto); +}; diff --git a/interface/numdlg.h b/interface/numdlg.h new file mode 100644 index 0000000000..527a873116 --- /dev/null +++ b/interface/numdlg.h @@ -0,0 +1,31 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: numdlg.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + Shows a dialog asking the user for numeric input. The dialogs title is set to + @e caption, it contains a (possibly) multiline @e message above the + single line @e prompt and the zone for entering the number. + + The number entered must be in the range @e min..@e max (both of which + should be positive) and @e value is the initial value of it. If the user + enters an invalid value or cancels the dialog, the function will return -1. + + Dialog is centered on its @e parent unless an explicit position is given in + @e pos. +*/ +long wxGetNumberFromUser(const wxString& message, + const wxString& prompt, + const wxString& caption, + long value, + long min = 0, + long max = 100, + wxWindow * parent = @NULL, + const wxPoint& pos = wxDefaultPosition); + + + \ No newline at end of file diff --git a/interface/object.h b/interface/object.h new file mode 100644 index 0000000000..429e7a5b59 --- /dev/null +++ b/interface/object.h @@ -0,0 +1,610 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: object.h +// Purpose: documentation for wxObjectRefData class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxObjectRefData + @wxheader{object.h} + + This class is used to store reference-counted data. Derive classes from this to + store your own data. When retrieving information from a @b wxObject's reference + data, + you will need to cast to your own derived class. + + @library{wxbase} + @category{FIXME} + + @seealso + wxObject, wxObjectDataPtrT, @ref overview_trefcount "Reference counting" +*/ +class wxObjectRefData +{ +public: + /** + Default constructor. Initialises the internal reference count to 1. + */ + wxObjectRefData(); + + /** + Destructor. It's declared @c protected so that wxObjectRefData instances will + never + be destroyed directly but only as result of a DecRef() call. + */ + wxObjectRefData(); + + /** + Decrements the reference count associated with this shared data and, if it + reaches zero, + destroys this instance of wxObjectRefData releasing its memory. + + Please note that after calling this function, the caller should absolutely + avoid to use + the pointer to this instance since it may not be valid anymore. + */ + void DecRef(); + + /** + Returns the reference count associated with this shared data. + When this goes to zero during a DecRef() call, the object + will auto-free itself. + */ + int GetRefCount(); + + /** + Increments the reference count associated with this shared data. + */ + void IncRef(); +}; + + +/** + @class wxObject + @wxheader{object.h} + + This is the root class of many of the wxWidgets classes. + It declares a virtual destructor which ensures that + destructors get called for all derived class objects where necessary. + + wxObject is the hub of a dynamic object creation + scheme, enabling a program to create instances of a class only knowing + its string class name, and to query the class hierarchy. + + The class contains optional debugging versions + of @b new and @b delete, which can help trace memory allocation + and deallocation problems. + + wxObject can be used to implement @ref overview_trefcount "reference counted" + objects, + such as wxPen, wxBitmap and others (see @ref overview_refcountlist "this list"). + + @library{wxbase} + @category{rtti} + + @seealso + wxClassInfo, @ref overview_debuggingoverview "Debugging overview", + wxObjectRefData +*/ +class wxObject +{ +public: + //@{ + /** + Default and copy constructors. + */ + wxObject(); + wxObject(const wxObject& other); + //@} + + /** + Destructor. Performs dereferencing, for those objects + that use reference counting. + */ + wxObject(); + + /** + A virtual function that may be redefined by derived classes to allow dumping of + memory states. + + This function is only defined in debug build and doesn't exist at all if + @c __WXDEBUG__ is not defined. + + @param stream + Stream on which to output dump information. + + @remarks Currently wxWidgets does not define Dump for derived classes, + but programmers may wish to use it for their own + applications. Be sure to call the Dump member of the + class's base class to allow all information to be + dumped. + */ + void Dump(ostream& stream); + + /** + This virtual function is redefined for every class that requires run-time + type information, when using DECLARE_CLASS macros. + */ + wxClassInfo * GetClassInfo(); + + /** + Returns the @b m_refData pointer. + + @sa Ref(), UnRef(), wxObject::m_refData, SetRefData(), + wxObjectRefData + */ + wxObjectRefData* GetRefData(); + + /** + Determines whether this class is a subclass of (or the same class as) + the given class. + + @param info + A pointer to a class information object, which may be obtained + by using the CLASSINFO macro. + + @returns @true if the class represented by info is the same class as this + one or is derived from it. + */ + bool IsKindOf(wxClassInfo * info); + + /** + Returns @true if this object has the same data pointer as @e obj. Notice + that @true is returned if the data pointers are @NULL in both objects. + + This function only does a shallow comparison, i.e. it doesn't compare + the objects pointed to by the data pointers of these objects. + */ + bool IsSameAs(const wxObject& obj); + + /** + Makes this object refer to the data in @e clone. + + @param clone + The object to 'clone'. + + @remarks First this function calls UnRef() on itself to decrement + (and perhaps free) the data it is currently referring + to. + + @sa UnRef(), wxObject::m_refData, SetRefData(), + GetRefData(), wxObjectRefData + */ +#define void Ref(const wxObject& clone) /* implementation is private */ + + /** + Sets the @b m_refData pointer. + + @sa Ref(), UnRef(), wxObject::m_refData, GetRefData(), + wxObjectRefData + */ + void SetRefData(wxObjectRefData* data); + + /** + Decrements the reference count in the associated data, and if it is zero, + deletes the data. + The @b m_refData member is set to @NULL. + + @sa Ref(), wxObject::m_refData, SetRefData(), + GetRefData(), wxObjectRefData + */ + void UnRef(); + + /** + Ensure that this object's data is not shared with any other object. + + if we have no + data, it is created using CreateRefData() below, if we have shared data + it is copied using CloneRefData(), otherwise nothing is done. + */ + void UnShare(); + + /** + wxObjectRefData* m_refData + + Pointer to an object which is the object's reference-counted data. + + @sa Ref(), UnRef(), SetRefData(), + GetRefData(), wxObjectRefData + */ + + + /** + The @e delete operator is defined for debugging versions of the library only, + when + the identifier __WXDEBUG__ is defined. It takes over memory deallocation, + allowing + wxDebugContext operations. + */ + void delete(void buf); + + /** + The @e new operator is defined for debugging versions of the library only, when + the identifier __WXDEBUG__ is defined. It takes over memory allocation, allowing + wxDebugContext operations. + */ + void * new(size_t size, const wxString& filename = @NULL, + int lineNum = 0); +}; + + +/** + @class wxClassInfo + @wxheader{object.h} + + This class stores meta-information about classes. Instances of this class are + not generally defined directly by an application, but indirectly through use + of macros such as @b DECLARE_DYNAMIC_CLASS and @b IMPLEMENT_DYNAMIC_CLASS. + + @library{wxbase} + @category{rtti} + + @seealso + Overview, wxObject +*/ +class wxClassInfo +{ +public: + /** + Constructs a wxClassInfo object. The supplied macros implicitly construct + objects of this + class, so there is no need to create such objects explicitly in an application. + */ + wxClassInfo(const wxChar * className, + const wxClassInfo * baseClass1, + const wxClassInfo * baseClass2, + int size, wxObjectConstructorFn fn); + + /** + Creates an object of the appropriate kind. Returns @NULL if the class has not + been declared + dynamically creatable (typically, it is an abstract class). + */ + wxObject* CreateObject(); + + /** + Finds the wxClassInfo object for a class of the given string name. + */ + static wxClassInfo * FindClass(wxChar * name); + + /** + Returns the name of the first base class (@NULL if none). + */ + wxChar * GetBaseClassName1(); + + /** + Returns the name of the second base class (@NULL if none). + */ + wxChar * GetBaseClassName2(); + + /** + Returns the string form of the class name. + */ + wxChar * GetClassName(); + + /** + Returns the size of the class. + */ + int GetSize(); + + /** + Initializes pointers in the wxClassInfo objects for fast execution + of IsKindOf. Called in base wxWidgets library initialization. + */ + static void InitializeClasses(); + + /** + Returns @true if this class info can create objects of the associated class. + */ + bool IsDynamic(); + + /** + Returns @true if this class is a kind of (inherits from) the given class. + */ + bool IsKindOf(wxClassInfo* info); +}; + + +/** + @class wxObjectDataPtrT + @wxheader{object.h} + + This is helper template class primarily written to avoid memory + leaks because of missing calls to wxObjectRefData::DecRef. + + Despite the name this template can actually be used as a + smart pointer for any class implementing the reference + counting interface which only consists of the two methods + @b T::IncRef() and @b T::DecRef(). + + The difference to wxSharedPtr is that + wxObjectDataPtr relies on the reference counting to be in + the class pointed to where as wxSharedPtr implements the + reference counting itself. + + @library{wxbase} + @category{FIXME} + + @seealso + wxObject, wxObjectRefData, @ref overview_trefcount "Reference counting" +*/ +class wxObjectDataPtr +{ +public: + //@{ + /** + This copy constructor increases the count of the reference + counted object to which @e tocopy points and then this + class will point to, as well. + */ + wxObjectDataPtrT(T* ptr = @NULL); + wxObjectDataPtrT(const wxObjectDataPtr& tocopy); + //@} + + /** + Decreases the reference count of the object to which this + class points. + */ + ~wxObjectDataPtrT(); + + /** + Gets a pointer to the reference counted object to which + this class points. + */ + T* get(); + + /** + Conversion to a boolean expression (in a variant which is not + convertable to anything but a boolean expression). If this class + contains a valid pointer it will return @e @true, if it contains + a @NULL pointer it will return @e @false. + */ + operator unspecified_bool_type(); + + /** + Returns a reference to the object. If the internal pointer is @NULL + this method will cause an assert in debug mode. + */ + T operator*(); + + /** + Returns a pointer to the reference counted object to which + this class points. If this the internal pointer is @NULL, + this method will assert in debug mode. + */ + T* operator-(); + + //@{ + /** + Assignment operators. + */ + wxObjectDataPtrT& operator operator=(const wxObjectDataPtr& tocopy); + wxObjectDataPtrT& operator operator=(T* ptr); + //@} +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Used inside a class declaration to declare that the class should be + made known to the class hierarchy, but objects of this class cannot be created + dynamically. The same as DECLARE_ABSTRACT_CLASS. +*/ +#define DECLARE_CLASS() /* implementation is private */ + +/** + Used inside a class declaration to declare that the class should be + made known to the class hierarchy, but objects of this class cannot be created + dynamically. The same as DECLARE_CLASS. + + Example: + @code + class wxCommand: public wxObject + { + DECLARE_ABSTRACT_CLASS(wxCommand) + + private: + ... + public: + ... + }; + @endcode +*/ +#define DECLARE_ABSTRACT_CLASS() /* implementation is private */ + +/** + Returns a pointer to the wxClassInfo object associated with this class. +*/ +#define wxClassInfo * CLASSINFO() /* implementation is private */ + +/** + Same as @c reinterpret_castT(x) if the compiler supports reinterpret cast or + @c (T)x for old compilers. + + @sa wx_const_cast, wx_static_cast +*/ +T wx_reinterpret_cast(); + +/** + Used in a C++ implementation file to complete the declaration of a + class that has run-time type information and two base classes. The + same as IMPLEMENT_ABSTRACT_CLASS2. +*/ +#define IMPLEMENT_CLASS2() /* implementation is private */ + +/** + This macro expands into @c const_castclassname *(ptr) if the compiler + supports @e const_cast or into an old, C-style cast, otherwise. + + @sa wx_const_cast, wxDynamicCast, wxStaticCast +*/ +classname * wxConstCast(); + +/** + Used in a C++ implementation file to complete the declaration of + a class that has run-time type information. The same as IMPLEMENT_CLASS. + + Example: + @code + IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) + + wxCommand::wxCommand(void) + { + ... + } + @endcode +*/ +#define IMPLEMENT_ABSTRACT_CLASS() /* implementation is private */ + +/** + Used in a C++ implementation file to complete the declaration of + a class that has run-time type information. The same as + IMPLEMENT_ABSTRACT_CLASS. +*/ +#define IMPLEMENT_CLASS() /* implementation is private */ + +/** + This macro is equivalent to @c wxDynamicCast(this, classname) but the + latter provokes spurious compilation warnings from some compilers (because it + tests whether @c this pointer is non-@NULL which is always @true), so + this macro should be used to avoid them. + + @sa wxDynamicCast +*/ +classname * wxDynamicCastThis(); + +/** + Used in a C++ implementation file to complete the declaration of + a class that has run-time type information, and whose instances + can be created dynamically. Use this for classes derived from two + base classes. +*/ +#define IMPLEMENT_DYNAMIC_CLASS2() /* implementation is private */ + +/** + Creates and returns an object of the given class, if the class has been + registered with the dynamic class system using DECLARE... and IMPLEMENT... + macros. +*/ +wxObject * wxCreateDynamicObject(const wxString& className); + +/** + Used inside a class declaration to make the class known to wxWidgets RTTI + system and also declare that the objects of this class should be dynamically + creatable from run-time type information. Notice that this implies that the + class should have a default constructor, if this is not the case consider using + DECLARE_CLASS. + + Example: + @code + class wxFrame: public wxWindow + { + DECLARE_DYNAMIC_CLASS(wxFrame) + + private: + const wxString& frameTitle; + public: + ... + }; + @endcode +*/ +#define DECLARE_DYNAMIC_CLASS() /* implementation is private */ + +/** + Same as @c const_castT(x) if the compiler supports const cast or + @c (T)x for old compilers. Unlike wxConstCast, + the cast it to the type @e T and not to @c T * and also the order of + arguments is the same as for the standard cast. + + @sa wx_reinterpret_cast, wx_static_cast +*/ +T wx_const_cast(); + +/** + Used in a C++ implementation file to complete the declaration of + a class that has run-time type information and two base classes. The same as + IMPLEMENT_CLASS2. +*/ +#define IMPLEMENT_ABSTRACT_CLASS2() /* implementation is private */ + +/** + This macro returns the pointer @e ptr cast to the type @e classname * if + the pointer is of this type (the check is done during the run-time) or + @NULL otherwise. Usage of this macro is preferred over obsoleted + wxObject::IsKindOf() function. + + The @e ptr argument may be @NULL, in which case @NULL will be + returned. + + Example: + @code + wxWindow *win = wxWindow::FindFocus(); + wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl); + if ( text ) + { + // a text control has the focus... + } + else + { + // no window has the focus or it is not a text control + } + @endcode + + @sa @ref overview_runtimeclassoverview "RTTI overview", wxDynamicCastThis, + wxConstCast, wxStaticCast +*/ +classname * wxDynamicCast(); + +/** + This is defined in debug mode to be call the redefined new operator + with filename and line number arguments. The definition is: + @code + #define WXDEBUG_NEW new(__FILE__,__LINE__) + @endcode + + In non-debug mode, this is defined as the normal new operator. +*/ +#define WXDEBUG_NEW() /* implementation is private */ + +/** + This macro checks that the cast is valid in debug mode (an assert failure will + result if @c wxDynamicCast(ptr, classname) == @NULL) and then returns the + result of executing an equivalent of @c static_castclassname *(ptr). + + @sa wx_static_cast, wxDynamicCast, wxConstCast +*/ +classname * wxStaticCast(); + +/** + Same as @c static_castT(x) if the compiler supports static cast or + @c (T)x for old compilers. Unlike wxStaticCast, + there are no checks being done and the meaning of the macro arguments is exactly + the same as for the standard static cast, i.e. @e T is the full type name and + star is not appended to it. + + @sa wx_const_cast, wx_reinterpret_cast, wx_truncate_cast +*/ +T wx_static_cast(); + +/** + Used in a C++ implementation file to complete the declaration of + a class that has run-time type information, and whose instances + can be created dynamically. + + Example: + @code + IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) + + wxFrame::wxFrame(void) + { + ... + } + @endcode +*/ +#define IMPLEMENT_DYNAMIC_CLASS() /* implementation is private */ + diff --git a/interface/odcombo.h b/interface/odcombo.h new file mode 100644 index 0000000000..233b87e6cf --- /dev/null +++ b/interface/odcombo.h @@ -0,0 +1,197 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: odcombo.h +// Purpose: documentation for wxOwnerDrawnComboBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxOwnerDrawnComboBox + @wxheader{odcombo.h} + + wxOwnerDrawnComboBox is a combobox with owner-drawn list items. + In essence, it is a wxComboCtrl with + wxVListBox popup and wxControlWithItems + interface. + + Implementing item drawing and measuring is similar to wxVListBox. + Application needs to subclass wxOwnerDrawnComboBox and implement + wxOwnerDrawnComboBox::OnDrawItem, wxOwnerDrawnComboBox::OnMeasureItem + and wxOwnerDrawnComboBox::OnMeasureItemWidth. + + @beginStyleTable + @style{wxODCB_DCLICK_CYCLES}: + Double-clicking cycles item if wxCB_READONLY is also used. + Synonymous with wxCC_SPECIAL_DCLICK. + @style{wxODCB_STD_CONTROL_PAINT}: + Control itself is not custom painted using OnDrawItem. Even if this + style is not used, writable wxOwnerDrawnComboBox is never custom + painted unless SetCustomPaintWidth is called. + @endStyleTable + + @beginEventTable + @event{EVT_COMBOBOX(id\, func)}: + Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on + the list is selected. Note that calling GetValue returns the new + value of selection. + @endEventTable + + @library{wxadv} + @category{ctrl} + @appearance{ownerdrawncombobox.png} + + @seealso + wxComboCtrl, wxComboBox, wxVListBox, wxCommandEvent +*/ +class wxOwnerDrawnComboBox : public wxComboCtrl +{ +public: + //@{ + /** + Constructor, creating and showing a owner-drawn combobox. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param value + Initial selection string. An empty string indicates no selection. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param n + Number of strings with which to initialise the control. + + @param choices + An array of strings with which to initialise the control. + + @param style + Window style. See wxOwnerDrawnComboBox. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxOwnerDrawnComboBox(); + wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = @NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Destructor, destroying the owner-drawn combobox. + */ + ~wxOwnerDrawnComboBox(); + + //@{ + /** + Creates the combobox for two-step construction. Derived classes + should call or replace this function. See + wxOwnerDrawnComboBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Returns index to the widest item in the list. + */ + int GetWidestItem(); + + /** + Returns width of the widest item in the list. + */ + int GetWidestItemWidth(); + + /** + This method is used to draw the items background and, maybe, a border around it. + + The base class version implements a reasonable default behaviour which consists + in drawing the selected item with the standard background colour and drawing a + border around the item if it is either selected or current. + + @remarks flags has the same meaning as with OnDrawItem. + */ + void OnDrawBackground(wxDC& dc, const wxRect& rect, int item, + int flags); + + /** + The derived class may implement this function to actually draw the item + with the given index on the provided DC. If function is not implemented, + the item text is simply drawn, as if the control was a normal combobox. + + @param dc + The device context to use for drawing + + @param rect + The bounding rectangle for the item being drawn (DC clipping + region is set to this rectangle before calling this function) + + @param item + The index of the item to be drawn + + @param flags + Combines any of the following flag values: + */ + void OnDrawItem(wxDC& dc, const wxRect& rect, int item, + int flags); + + /** + The derived class may implement this method to return the height of the + specified item (in pixels). + + The default implementation returns text height, as if this control was + a normal combobox. + */ + wxCoord OnMeasureItem(size_t item); + + /** + The derived class may implement this method to return the width of the + specified item (in pixels). If -1 is returned, then the item text width + is used. + + The default implementation returns -1. + */ + wxCoord OnMeasureItemWidth(size_t item); +}; diff --git a/interface/palette.h b/interface/palette.h new file mode 100644 index 0000000000..b408669179 --- /dev/null +++ b/interface/palette.h @@ -0,0 +1,155 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: palette.h +// Purpose: documentation for wxPalette class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPalette + @wxheader{palette.h} + + A palette is a table that maps pixel values to RGB colours. It allows the + colours of a low-depth bitmap, for example, to be mapped to the available + colours in a display. The notion of palettes is becoming more and more + obsolete nowadays and only the MSW port is still using a native palette. + All other ports use generic code which is basically just an array of + colours. + + It is likely that in the future the only use for palettes within wxWidgets + will be for representing colour indeces from images (such as GIF or PNG). + The image handlers for these formats have been modified to create a palette + if there is such information in the original image file (usually 256 or less + colour images). See wxImage for more information. + + @library{wxcore} + @category{gdi} + + @stdobjects + Objects: + wxNullPalette + + @seealso + wxDC::SetPalette, wxBitmap +*/ +class wxPalette : public wxGDIObject +{ +public: + //@{ + /** + Creates a palette from arrays of size @e n, one for each + red, blue or green component. + + @param palette + A pointer or reference to the palette to copy. + + @param n + The number of indices in the palette. + + @param red + An array of red values. + + @param green + An array of green values. + + @param blue + An array of blue values. + + @sa Create() + */ + wxPalette(); + wxPalette(const wxPalette& palette); + wxPalette(int n, const unsigned char* red, + const unsigned char* green, + const unsigned char* blue); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxPalette(); + + /** + Creates a palette from arrays of size @e n, one for each + red, blue or green component. + + @param n + The number of indices in the palette. + + @param red + An array of red values. + + @param green + An array of green values. + + @param blue + An array of blue values. + + @returns @true if the creation was successful, @false otherwise. + + @sa wxPalette() + */ + bool Create(int n, const unsigned char* red, + const unsigned char* green, + const unsigned char* blue); + + /** + Returns number of entries in palette. + */ + int GetColoursCount(); + + /** + Returns a pixel value (index into the palette) for the given RGB values. + + @param red + Red value. + + @param green + Green value. + + @param blue + Blue value. + + @returns The nearest palette index or wxNOT_FOUND for unexpected errors. + + @sa GetRGB() + */ + int GetPixel(unsigned char red, unsigned char green, + unsigned char blue); + + /** + Returns RGB values for a given palette index. + + @param pixel + The palette index. + + @param red + Receives the red value. + + @param green + Receives the green value. + + @param blue + Receives the blue value. + + @returns @true if the operation was successful. + + @sa GetPixel() + */ +#define bool GetRGB(int pixel, const unsigned char* red, + const unsigned char* green, + const unsigned char* blue) /* implementation is private */ + + /** + Returns @true if palette data is present. + */ +#define bool IsOk() /* implementation is private */ + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxPalette operator =(const wxPalette& palette); +}; diff --git a/interface/panel.h b/interface/panel.h new file mode 100644 index 0000000000..e62c69a78a --- /dev/null +++ b/interface/panel.h @@ -0,0 +1,139 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: panel.h +// Purpose: documentation for wxPanel class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPanel + @wxheader{panel.h} + + A panel is a window on which controls are placed. It is usually placed within + a frame. Its main feature over its parent class wxWindow is code for handling + child windows and TAB traversal. Since wxWidgets 2.9, there is support both + for TAB traversal implemented by wxWidgets itself as well as native TAB + traversal (such as for GTK 2.0). + + @e Note: Tab traversal is implemented through an otherwise undocumented + intermediate wxControlContainer class from which any class can derive + in addition to the normal wxWindow base class. Please see wx/containr.h + and wx/panel.h to find out how this is achieved. + + @e Note: if not all characters are being intercepted by your OnKeyDown or + OnChar handler, it may be because you are using the wxTAB_TRAVERSAL style, + which grabs some keypresses for use by child controls. + + @library{wxbase} + @category{miscwnd} + + @seealso + wxDialog +*/ +class wxPanel : public wxWindow +{ +public: + //@{ + /** + Constructor. + + @param parent + The parent window. + + @param id + An identifier for the panel. A value of -1 is taken to mean a default. + + @param pos + The panel position. The value wxDefaultPosition indicates a default position, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param size + The panel size. The value wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. + + @param style + The window style. See wxPanel. + + @param name + Used to associate a name with the window, + allowing the application user to set Motif resource values for + individual dialog boxes. + + @sa Create() + */ + wxPanel(); + wxPanel(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTAB_TRAVERSAL, + const wxString& name = "panel"); + //@} + + /** + Destructor. Deletes any child windows before deleting the physical window. + */ + ~wxPanel(); + + /** + This method is overridden from wxWindow::AcceptsFocus + and returns @true only if there is no child window in the panel which + can accept the focus. This is reevaluated each time a child + window is added or removed from the panel. + */ + bool AcceptsFocus(); + + /** + Used for two-step panel construction. See wxPanel() + for details. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTAB_TRAVERSAL, + const wxString& name = "panel"); + + /** + Sends a wxInitDialogEvent, which + in turn transfers data to the dialog via validators. + + @sa wxInitDialogEvent + */ + void InitDialog(); + + /** + The default handler for wxEVT_SYS_COLOUR_CHANGED. + + @param event + The colour change event. + + @remarks Changes the panel's colour to conform to the current settings + (Windows only). Add an event table entry for your + panel class if you wish the behaviour to be different + (such as keeping a user-defined background colour). + If you do override this function, call wxEvent::Skip + to propagate the notification to child windows and + controls. + + @sa wxSysColourChangedEvent + */ + void OnSysColourChanged(wxSysColourChangedEvent& event); + + /** + Overrides wxWindow::SetFocus. This method + uses the (undocumented) mix-in class wxControlContainer which manages + the focus and TAB logic for controls which usually have child controls. + In practice, if you call this method and the control has at least + one child window, the focus will be given to the child window. + + @sa wxFocusEvent, wxWindow::SetFocus + */ + virtual void SetFocus(); + + /** + In contrast to SetFocus() (see above) + this will set the focus to the panel even if there are child windows + in the panel. This is only rarely needed. + */ + virtual void SetFocusIgnoringChildren(); +}; diff --git a/interface/pen.h b/interface/pen.h new file mode 100644 index 0000000000..ace4975f51 --- /dev/null +++ b/interface/pen.h @@ -0,0 +1,313 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: pen.h +// Purpose: documentation for wxPen class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPen + @wxheader{pen.h} + + A pen is a drawing tool for drawing outlines. It is used for drawing + lines and painting the outline of rectangles, ellipses, etc. It has a + colour, a width and a style. + + @library{wxcore} + @category{gdi} + + @stdobjects + Objects: + wxNullPen + Pointers: + wxRED_PEN + + wxCYAN_PEN + + wxGREEN_PEN + + wxBLACK_PEN + + wxWHITE_PEN + + wxTRANSPARENT_PEN + + wxBLACK_DASHED_PEN + + wxGREY_PEN + + wxMEDIUM_GREY_PEN + + wxLIGHT_GREY_PEN + + @seealso + wxPenList, wxDC, wxDC::SetPen +*/ +class wxPen : public wxGDIObject +{ +public: + //@{ + /** + Copy constructor, uses @ref overview_trefcount "reference counting". + + @param colour + A colour object. + + @param colourName + A colour name. + + @param width + Pen width. Under Windows, the pen width cannot be greater than 1 if + the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH. + + @param stipple + A stipple bitmap. + + @param pen + A pointer or reference to a pen to copy. + + @param style + The style may be one of the following: + + wxSOLID + + + Solid style. + + wxTRANSPARENT + + + No pen is used. + + wxDOT + + + Dotted style. + + wxLONG_DASH + + + Long dashed style. + + wxSHORT_DASH + + + Short dashed style. + + wxDOT_DASH + + + Dot and dash style. + + wxSTIPPLE + + + Use the stipple bitmap. + + wxUSER_DASH + + + Use the user dashes: see SetDashes(). + + wxBDIAGONAL_HATCH + + + Backward diagonal hatch. + + wxCROSSDIAG_HATCH + + + Cross-diagonal hatch. + + wxFDIAGONAL_HATCH + + + Forward diagonal hatch. + + wxCROSS_HATCH + + + Cross hatch. + + wxHORIZONTAL_HATCH + + + Horizontal hatch. + + wxVERTICAL_HATCH + + + Vertical hatch. + + @remarks Different versions of Windows and different versions of other + platforms support very different subsets of the + styles above - there is no similarity even between + Windows95 and Windows98 - so handle with care. + + @sa SetStyle(), SetColour(), SetWidth(), SetStipple() + */ + wxPen(); + wxPen(const wxColour& colour, int width = 1, + int style = wxSOLID); + wxPen(const wxString& colourName, int width, int style); + wxPen(const wxBitmap& stipple, int width); + wxPen(const wxPen& pen); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + + @remarks Although all remaining pens are deleted when the application + exits, the application should try to clean up all + pens itself. This is because wxWidgets cannot know if + a pointer to the pen object is stored in an + application data structure, and there is a risk of + double deletion. + */ + ~wxPen(); + + /** + Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b + wxCAP_PROJECTING and + @b wxCAP_BUTT. The default is @b wxCAP_ROUND. + + @sa SetCap() + */ + int GetCap(); + + /** + Returns a reference to the pen colour. + + @sa SetColour() + */ + wxColour GetColour(); + + /** + Gets an array of dashes (defined as char in X, DWORD under Windows). + @e dashes is a pointer to the internal array. Do not deallocate or store this + pointer. + The function returns the number of dashes associated with this pen. + + @sa SetDashes() + */ + int GetDashes(wxDash** dashes); + + /** + Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b + wxJOIN_ROUND and + @b wxJOIN_MITER. The default is @b wxJOIN_ROUND. + + @sa SetJoin() + */ + int GetJoin(); + + /** + Gets a pointer to the stipple bitmap. + + @sa SetStipple() + */ + wxBitmap* GetStipple(); + + /** + Returns the pen style. + + @sa wxPen(), SetStyle() + */ + int GetStyle(); + + /** + Returns the pen width. + + @sa SetWidth() + */ + int GetWidth(); + + /** + Returns @true if the pen is initialised. + */ +#define bool IsOk() /* implementation is private */ + + /** + Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING + and + @b wxCAP_BUTT. The default is @b wxCAP_ROUND. + + @sa GetCap() + */ + void SetCap(int capStyle); + + //@{ + /** + The pen's colour is changed to the given colour. + + @sa GetColour() + */ + void SetColour(wxColour& colour); + void SetColour(const wxString& colourName); + void SetColour(unsigned char red, unsigned char green, + unsigned char blue); + //@} + + /** + Associates an array of pointers to dashes (defined as char in X, DWORD under + Windows) + with the pen. The array is not deallocated by wxPen, but neither must it be + deallocated by the calling application until the pen is deleted or this + function is called with a @NULL array. + + @sa GetDashes() + */ + void SetDashes(int n, wxDash* dashes); + + /** + Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND + and + @b wxJOIN_MITER. The default is @b wxJOIN_ROUND. + + @sa GetJoin() + */ + void SetJoin(int join_style); + + /** + Sets the bitmap for stippling. + + @sa GetStipple() + */ + void SetStipple(wxBitmap* stipple); + + /** + Set the pen style. + + @sa wxPen() + */ + void SetStyle(int style); + + /** + Sets the pen width. + + @sa GetWidth() + */ + void SetWidth(int width); + + /** + Inequality operator. + See @ref overview_refcountequality "reference-counted object comparison" for + more info. + */ + bool operator !=(const wxPen& pen); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxPen operator =(const wxPen& pen); + + /** + Equality operator. + See @ref overview_refcountequality "reference-counted object comparison" for + more info. + */ + bool operator ==(const wxPen& pen); +}; diff --git a/interface/pickerbase.h b/interface/pickerbase.h new file mode 100644 index 0000000000..278dccba6c --- /dev/null +++ b/interface/pickerbase.h @@ -0,0 +1,109 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: pickerbase.h +// Purpose: documentation for wxPickerBase class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPickerBase + @wxheader{pickerbase.h} + + Base abstract class for all pickers which support an auxiliary text control. + This class handles all positioning and sizing of the text control like a + an horizontal wxBoxSizer would do, with the text control on + the left of the picker button. + The proportion (see wxSizer documentation for more info about + proportion values) of the picker control defaults to 1 when there isn't a text + control + associated (see @c wxPB_USE_TEXTCTRL style) and to 0 otherwise. + + @beginStyleTable + @style{wxPB_USE_TEXTCTRL}: + Creates a text control to the left of the picker which is + completely managed by this wxPickerBase class. + @endStyleTable + + @library{wxcore} + @category{FIXME} + + @seealso + wxColourPickerCtrl +*/ +class wxPickerBase : public wxControl +{ +public: + /** + Returns the margin (in pixel) between the picker and the text control. + This function can be used only when HasTextCtrl() returns @true. + */ + int GetInternalMargin(); + + /** + Returns the proportion value of the picker. + */ + int GetPickerCtrlProportion(); + + /** + Returns a pointer to the text control handled by this window or @NULL if the + @b wxPB_USE_TEXTCTRL style was not specified when this control was created. + Very important: the contents of the text control could be containing an invalid + representation of the entity which can be chosen through the picker (e.g. the user entered an invalid colour syntax because of a typo). Thus you should never parse the content of the textctrl to get the user's input; rather use the derived-class getter (e.g. wxColourPickerCtrl::GetColour, wxFilePickerCtrl::GetPath, etc). + */ + wxTextCtrl * GetTextCtrl(); + + /** + Returns the proportion value of the text control. + This function can be used only when HasTextCtrl() returns @true. + */ + int GetTextCtrlProportion(); + + /** + Returns @true if this window has a valid text control (i.e. if the @b + wxPB_USE_TEXTCTRL style was + given when creating this control). + */ + bool HasTextCtrl(); + + /** + Returns @true if the picker control is growable. + */ + bool IsPickerCtrlGrowable(); + + /** + Returns @true if the text control is growable. + This function can be used only when HasTextCtrl() returns @true. + */ + bool IsTextCtrlGrowable(); + + /** + Sets the margin (in pixel) between the picker and the text control. + This function can be used only when HasTextCtrl() returns @true. + */ + void SetInternalMargin(int margin); + + /** + Sets the picker control as growable when @c grow is @true. + */ + void SetPickerCtrlGrowable(bool grow = @true); + + /** + Sets the proportion value of the picker. + Look at the overview of wxPickerBase for more details about this. + */ + void SetPickerCtrlProportion(int prop); + + /** + Sets the text control as growable when @c grow is @true. + This function can be used only when HasTextCtrl() returns @true. + */ + void SetTextCtrlGrowable(bool grow = @true); + + /** + Sets the proportion value of the text control. + Look at the overview of wxPickerBase for more details about this. + This function can be used only when HasTextCtrl() returns @true. + */ + void SetTextCtrlProportion(int prop); +}; diff --git a/interface/platform.h b/interface/platform.h new file mode 100644 index 0000000000..31a871d03e --- /dev/null +++ b/interface/platform.h @@ -0,0 +1,56 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: platform.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + Same as wxCHECK_VERSION but also checks that + @c wxSUBRELEASE_NUMBER is at least @e subrel. +*/ +#define bool wxCHECK_VERSION_FULL(major, minor, release, subrel) /* implementation is private */ + + + /** + This is a macro which evaluates to @true if the current wxWidgets version is at + least major.minor.release. + + For example, to test if the program is compiled with wxWidgets 2.2 or higher, + the following can be done: + @code + wxString s; + #if wxCHECK_VERSION(2, 2, 0) + if ( s.StartsWith("foo") ) + #else // replacement code for old version + if ( strncmp(s, "foo", 3) == 0 ) + #endif + { + ... + } + @endcode +*/ +#define bool wxCHECK_VERSION(major, minor, release) /* implementation is private */ + +/** + Returns 1 if the compiler being used to compile the code is Visual C++ + compiler version @e major or greater. Otherwise, and also if + the compiler is not Visual C++ at all, returns 0. +*/ +#define bool wxCHECK_VISUALC_VERSION(major) /* implementation is private */ + +/** + Returns 1 if the compiler being used to compile the code is GNU C++ + compiler (g++) version major.minor or greater. Otherwise, and also if + the compiler is not GNU C++ at all, returns 0. +*/ +#define bool wxCHECK_GCC_VERSION(major, minor) /* implementation is private */ + +/** + Returns 1 if the compiler being used to compile the code is Sun CC Pro + compiler and its version is at least @c major.minor. Otherwise returns + 0. +*/ +#define bool wxCHECK_SUNCC_VERSION(major, minor) /* implementation is private */ + diff --git a/interface/platinfo.h b/interface/platinfo.h new file mode 100644 index 0000000000..6f809ec28f --- /dev/null +++ b/interface/platinfo.h @@ -0,0 +1,246 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: platinfo.h +// Purpose: documentation for wxPlatformInfo class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPlatformInfo + @wxheader{platinfo.h} + + This class holds informations about the operating system and the toolkit that + the application + is running under and some basic architecture info of the machine where it's + running. + + @library{wxbase} + @category{FIXME} + + @seealso + wxGetOSVersion, wxIsPlatformLittleEndian, wxIsPlatform64Bit, wxAppTraits +*/ +class wxPlatformInfo : public wxObject +{ +public: + //@{ + /** + Initializes the object using given values. + */ + wxPlatformInfo(); + wxPlatformInfo(wxPortId pid = wxPORT_UNKNOWN, + int tkMajor = -1, + int tkMinor = -1, + wxOperatingSystemId id = wxOS_UNKNOWN, + int osMajor = -1, + int osMinor = -1, + wxArchitecture arch = wxARCH_INVALID, + wxEndianness endian = wxENDIAN_INVALID); + //@} + + /** + Returns @true if the OS version is at least @c major.minor. + + @sa GetOSMajorVersion(), GetOSMinorVersion(), + CheckToolkitVersion() + */ + bool CheckOSVersion(int major, int minor); + + /** + Returns @true if the toolkit version is at least @c major.minor. + + @sa GetToolkitMajorVersion(), + GetToolkitMinorVersion(), + CheckOSVersion() + */ + bool CheckToolkitVersion(int major, int minor); + + /** + Returns the global wxPlatformInfo object, initialized with the values for the + currently running platform. + */ +#define static const wxPlatformInfo Get() /* implementation is private */ + + /** + Converts the given string to a wxArchitecture enum value or to + wxARCH_INVALID if the given string is not a valid architecture string + (i.e. does not contain nor @c 32 nor @c 64 strings). + */ + static wxArchitecture GetArch(const wxString& arch); + + //@{ + /** + Returns the name for the architecture of this wxPlatformInfo instance. + */ + static wxString GetArchName(wxArchitecture arch); + wxString GetArchName(); + //@} + + /** + Returns the architecture ID of this wxPlatformInfo instance. + */ + wxArchitecture GetArchitecture(); + + //@{ + /** + Returns the endianness ID of this wxPlatformInfo instance. + */ + static wxEndianness GetEndianness(const wxString& end); + wxEndianness GetEndianness(); + //@} + + //@{ + /** + Returns the name for the endianness of this wxPlatformInfo instance. + */ + static wxString GetEndiannessName(wxEndianness end); + wxString GetEndiannessName(); + //@} + + /** + Returns the run-time major version of the OS associated with this + wxPlatformInfo instance. + See wxGetOsVersion for more info. + + @sa CheckOSVersion() + */ + int GetOSMajorVersion(); + + /** + Returns the run-time minor version of the OS associated with this + wxPlatformInfo instance. + See wxGetOsVersion for more info. + + @sa CheckOSVersion() + */ + int GetOSMinorVersion(); + + //@{ + /** + Returns the operating system family name of the OS associated with this + wxPlatformInfo instance. + */ + static wxString GetOperatingSystemFamilyName(wxOperatingSystemId os); + wxString GetOperatingSystemFamilyName(); + //@} + + //@{ + /** + Returns the operating system ID of this wxPlatformInfo instance. + */ + static wxOperatingSystemId GetOperatingSystemId(const wxString& name); + wxOperatingSystemId GetOperatingSystemId(); + //@} + + //@{ + /** + Returns the operating system name of the OS associated with this wxPlatformInfo + instance. + */ + static wxString GetOperatingSystemIdName(wxOperatingSystemId os); + wxString GetOperatingSystemIdName(); + //@} + + //@{ + /** + Returns the wxWidgets port ID associated with this wxPlatformInfo instance. + */ + static wxPortId GetPortId(const wxString& portname); + wxPortId GetPortId(); + //@} + + //@{ + /** + Returns the name of the wxWidgets port ID associated with this wxPlatformInfo + instance. + */ + static wxString GetPortIdName(wxPortId port, bool usingUniversal); + wxString GetPortIdName(); + //@} + + //@{ + /** + Returns the short name of the wxWidgets port ID associated with this + wxPlatformInfo instance. + */ + static wxString GetPortIdShortName(wxPortId port, + bool usingUniversal); + wxString GetPortIdShortName(); + //@} + + /** + Returns the run-time major version of the toolkit associated with this + wxPlatformInfo instance. + Note that if GetPortId() returns wxPORT_BASE, then this value is zero (unless + externally modified with wxPlatformInfo::SetToolkitVersion); that is, no native toolkit is in use. + + See wxAppTraits::GetToolkitVersion for more info. + + @sa CheckToolkitVersion() + */ + int GetToolkitMajorVersion(); + + /** + Returns the run-time minor version of the toolkit associated with this + wxPlatformInfo instance. + Note that if GetPortId() returns wxPORT_BASE, then this value is zero (unless + externally modified with wxPlatformInfo::SetToolkitVersion); that is, no native toolkit is in use. + + See wxAppTraits::GetToolkitVersion for more info. + + @sa CheckToolkitVersion() + */ + int GetToolkitMinorVersion(); + + /** + Returns @true if this instance is fully initialized with valid values. + */ +#define bool IsOk() /* implementation is private */ + + /** + Returns @true if this wxPlatformInfo describes wxUniversal build. + */ + bool IsUsingUniversalWidgets(); + + /** + Sets the architecture enum value associated with this wxPlatformInfo instance. + */ + void SetArchitecture(wxArchitecture n); + + /** + Sets the endianness enum value associated with this wxPlatformInfo instance. + */ + void SetEndianness(wxEndianness n); + + /** + Sets the version of the operating system associated with this wxPlatformInfo + instance. + */ + void SetOSVersion(int major, int minor); + + /** + Sets the operating system associated with this wxPlatformInfo instance. + */ + void SetOperatingSystemId(wxOperatingSystemId n); + + /** + Sets the wxWidgets port ID associated with this wxPlatformInfo instance. + */ + void SetPortId(wxPortId n); + + /** + Sets the version of the toolkit associated with this wxPlatformInfo instance. + */ + void SetToolkitVersion(int major, int minor); + + /** + Inequality operator. Tests all class' internal variables. + */ + bool operator!=(const wxPlatformInfo& t); + + /** + Equality operator. Tests all class' internal variables. + */ + bool operator==(const wxPlatformInfo& t); +}; diff --git a/interface/position.h b/interface/position.h new file mode 100644 index 0000000000..19e54580b1 --- /dev/null +++ b/interface/position.h @@ -0,0 +1,80 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: position.h +// Purpose: documentation for wxPosition class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPosition + @wxheader{position.h} + + This class represents the position of an item in any kind of grid of rows and + columns such as wxGridBagSizer, or + wxHVScrolledWindow. + + @library{wxbase} + @category{FIXME} + + @seealso + wxPoint, wxSize +*/ +class wxPosition +{ +public: + //@{ + /** + Construct a new wxPosition, optionally setting the row and column. The + default value is (0, 0). + */ + wxPosition(); + wxPosition(int row, int col); + //@} + + /** + A synonym for GetColumn(). + */ + int GetCol(); + + /** + Get the current row value. + */ + int GetColumn(); + + /** + Get the current row value. + */ + int GetRow(); + + //@{ + /** + + */ + bool operator ==(const wxPosition& p); + bool operator !=(const wxPosition& p); + wxPosition operator +=(const wxPosition& p); + wxPosition operator -=(const wxPosition& p); + wxPosition operator +=(const wxSize& s); + wxPosition operator -=(const wxSize& s); + wxPosition operator +(const wxPosition& p); + wxPosition operator -(const wxPosition& p); + wxPosition operator +(const wxSize& s); + wxPosition operator -(const wxSize& s); + //@} + + /** + A synonym for SetColumn(). + */ + void SetCol(int column); + + /** + Set a new column value. + */ + void SetColumn(int column); + + /** + Set a new row value. + */ + void SetRow(int row); +}; diff --git a/interface/power.h b/interface/power.h new file mode 100644 index 0000000000..316db2115f --- /dev/null +++ b/interface/power.h @@ -0,0 +1,38 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: power.h +// Purpose: documentation for wxPowerEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPowerEvent + @wxheader{power.h} + + The power events are generated when the system power state changes, e.g. the + system is suspended, hibernated, plugged into or unplugged from the wall socket + and so on. + + Notice that currently only suspend and resume events are generated and only + under MS Windows platform. To avoid the need to change the code using this + event later when these events are implemented on the other platforms please use + the test @c ifdef wxHAS_POWER_EVENTS instead of directly testing for + the platform in your code: this symbol will be defined for all platforms + supporting the power events. + + @library{wxbase} + @category{FIXME} + + @seealso + wxGetPowerType, wxGetBatteryState +*/ +class wxPowerEvent : public wxEvent +{ +public: + /** + Call this to prevent suspend from taking place in + @c wxEVT_POWER_SUSPENDING handler (it is ignored for all the others). + */ + void Veto(); +}; diff --git a/interface/print.h b/interface/print.h new file mode 100644 index 0000000000..84f48814be --- /dev/null +++ b/interface/print.h @@ -0,0 +1,753 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: print.h +// Purpose: documentation for wxPreviewControlBar class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPreviewControlBar + @wxheader{print.h} + + This is the default implementation of the preview control bar, a panel + with buttons and a zoom control. You can derive a new class from this and + override some or all member functions to change the behaviour and appearance; + or you can leave it as it is. + + @library{wxbase} + @category{printing} + + @seealso + wxPreviewFrame, wxPreviewCanvas, wxPrintPreview +*/ +class wxPreviewControlBar : public wxPanel +{ +public: + /** + Destructor. + */ + ~wxPreviewControlBar(); + + /** + Creates buttons, according to value of the button style flags. + */ + void CreateButtons(); + + /** + Gets the print preview object associated with the control bar. + */ + wxPrintPreview * GetPrintPreview(); + + /** + Gets the current zoom setting in percent. + */ + int GetZoomControl(); + + /** + Sets the zoom control. + */ + void SetZoomControl(int percent); + + /** + Constructor. + + The buttons parameter may be a combination of the following, using the bitwise + 'or' operator. + + wxPREVIEW_PRINT + + + Create a print button. + + wxPREVIEW_NEXT + + + Create a next page button. + + wxPREVIEW_PREVIOUS + + + Create a previous page button. + + wxPREVIEW_ZOOM + + + Create a zoom control. + + wxPREVIEW_DEFAULT + + + Equivalent to a combination of wxPREVIEW_PREVIOUS, wxPREVIEW_NEXT and + wxPREVIEW_ZOOM. + */ + wxPreviewControlBar(wxPrintPreview* preview, long buttons, + wxWindow* parent, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "panel"); +}; + + +/** + @class wxPreviewCanvas + @wxheader{print.h} + + A preview canvas is the default canvas used by the print preview + system to display the preview. + + @library{wxbase} + @category{printing} + + @seealso + wxPreviewFrame, wxPreviewControlBar, wxPrintPreview +*/ +class wxPreviewCanvas : public wxScrolledWindow +{ +public: + /** + Constructor. + */ + wxPreviewCanvas(wxPrintPreview* preview, wxWindow* parent, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "canvas"); + + /** + Destructor. + */ + ~wxPreviewCanvas(); + + /** + Calls wxPrintPreview::PaintPage to refresh the canvas. + */ + void OnPaint(wxPaintEvent& event); +}; + + +/** + @class wxPreviewFrame + @wxheader{print.h} + + This class provides the default method of managing the print preview interface. + Member functions may be overridden to replace functionality, or the + class may be used without derivation. + + @library{wxbase} + @category{printing} + + @seealso + wxPreviewCanvas, wxPreviewControlBar, wxPrintPreview +*/ +class wxPreviewFrame : public wxFrame +{ +public: + /** + Constructor. Pass a print preview object plus other normal frame arguments. + The print preview object will be destroyed by the frame when it closes. + */ + wxPreviewFrame(wxPrintPreview* preview, wxWindow* parent, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Destructor. + */ + ~wxPreviewFrame(); + + /** + Creates a wxPreviewCanvas. Override this function to allow + a user-defined preview canvas object to be created. + */ + void CreateCanvas(); + + /** + Creates a wxPreviewControlBar. Override this function to allow + a user-defined preview control bar object to be created. + */ + void CreateControlBar(); + + /** + Creates the preview canvas and control bar, and calls + wxWindow::MakeModal(@true) to disable other top-level windows + in the application. + + This function should be called by the application prior to + showing the frame. + */ + void Initialize(); + + /** + Enables the other frames in the application, and deletes the print preview + object, implicitly deleting any printout objects associated with the print + preview object. + */ + void OnCloseWindow(wxCloseEvent& event); +}; + + +/** + @class wxPrintPreview + @wxheader{print.h} + + Objects of this class manage the print preview process. The object is passed + a wxPrintout object, and the wxPrintPreview object itself is passed to + a wxPreviewFrame object. Previewing is started by initializing and showing + the preview frame. Unlike wxPrinter::Print, flow of control returns to the + application + immediately after the frame is shown. + + @library{wxbase} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", wxPrinterDC, + wxPrintDialog, wxPrintout, wxPrinter, wxPreviewCanvas, wxPreviewControlBar, wxPreviewFrame. +*/ +class wxPrintPreview : public wxObject +{ +public: + /** + Constructor. Pass a printout object, an optional printout object to be + used for actual printing, and the address of an optional + block of printer data, which will be copied to the print preview object's + print data. + + If @e printoutForPrinting is non-@NULL, a @b Print... button will be placed on + the + preview frame so that the user can print directly from the preview interface. + + Do not explicitly delete the printout objects once this destructor has been + called, since they will be deleted in the wxPrintPreview constructor. + The same does not apply to the @e data argument. + + Test the Ok member to check whether the wxPrintPreview object was created + correctly. + Ok could return @false if there was a problem initializing the printer device + context + (current printer not set, for example). + */ + wxPrintPreview(wxPrintout* printout, + wxPrintout* printoutForPrinting, + wxPrintData* data=@NULL); + + /** + Destructor. Deletes both print preview objects, so do not destroy these objects + in your application. + */ + ~wxPrinter(); + + /** + Gets the preview window used for displaying the print preview image. + */ + wxPreviewCanvas* GetCanvas(); + + /** + Gets the page currently being previewed. + */ + int GetCurrentPage(); + + /** + Gets the frame used for displaying the print preview canvas + and control bar. + */ + wxFrame * GetFrame(); + + /** + Returns the maximum page number. + */ + int GetMaxPage(); + + /** + Returns the minimum page number. + */ + int GetMinPage(); + + /** + Gets the preview printout object associated with the wxPrintPreview object. + */ + wxPrintout * GetPrintout(); + + /** + Gets the printout object to be used for printing from within the preview + interface, + or @NULL if none exists. + */ + wxPrintout * GetPrintoutForPrinting(); + + /** + Returns @true if the wxPrintPreview is valid, @false otherwise. It could return + @false if there was a + problem initializing the printer device context (current printer not set, for + example). + */ +#define bool Ok() /* implementation is private */ + + /** + This refreshes the preview window with the preview image. + It must be called from the preview window's OnPaint member. + + The implementation simply blits the preview bitmap onto + the canvas, creating a new preview bitmap if none exists. + */ + bool PaintPage(wxPreviewCanvas * canvas, wxDC dc); + + /** + Invokes the print process using the second wxPrintout object + supplied in the wxPrintPreview constructor. + Will normally be called by the @b Print... panel item on the + preview frame's control bar. + + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + */ + bool Print(bool prompt); + + /** + Renders a page into a wxMemoryDC. Used internally by wxPrintPreview. + */ + bool RenderPage(int pageNum); + + /** + Sets the window to be used for displaying the print preview image. + */ + void SetCanvas(wxPreviewCanvas* window); + + /** + Sets the current page to be previewed. + */ + void SetCurrentPage(int pageNum); + + /** + Sets the frame to be used for displaying the print preview canvas + and control bar. + */ + void SetFrame(wxFrame * frame); + + /** + Associates a printout object with the wxPrintPreview object. + */ + void SetPrintout(wxPrintout * printout); + + /** + Sets the percentage preview zoom, and refreshes the preview canvas + accordingly. + */ + void SetZoom(int percent); +}; + + +/** + @class wxPrinter + @wxheader{print.h} + + This class represents the Windows or PostScript printer, and is the vehicle + through + which printing may be launched by an application. Printing can also + be achieved through using of lower functions and classes, but + this and associated classes provide a more convenient and general + method of printing. + + @library{wxbase} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", wxPrinterDC, + wxPrintDialog, wxPrintout, wxPrintPreview. +*/ +class wxPrinter : public wxObject +{ +public: + /** + Constructor. Pass an optional pointer to a block of print + dialog data, which will be copied to the printer object's local data. + + @sa wxPrintDialogData, wxPrintData + */ + wxPrinter(wxPrintDialogData* data = @NULL); + + /** + Creates the default printing abort window, with a cancel button. + */ + void CreateAbortWindow(wxWindow* parent, wxPrintout* printout); + + /** + Returns @true if the user has aborted the print job. + */ + bool GetAbort(); + + /** + Return last error. Valid after calling Print(), + PrintDialog() or + wxPrintPreview::Print. These functions + set last error to @b wxPRINTER_NO_ERROR if no error happened. + + Returned value is one of the following: + + + @b wxPRINTER_NO_ERROR + + + No error happened. + + @b wxPRINTER_CANCELLED + + + The user cancelled printing. + + @b wxPRINTER_ERROR + + + There was an error during printing. + */ + static wxPrinterError GetLastError(); + + /** + Returns the @ref overview_wxprintdata "print data" associated with the printer + object. + */ + wxPrintDialogData GetPrintDialogData(); + + /** + Starts the printing process. Provide a parent window, a user-defined wxPrintout + object which controls + the printing of a document, and whether the print dialog should be invoked + first. + + Print could return @false if there was a problem initializing the printer device + context + (current printer not set, for example) or the user cancelled printing. Call + GetLastError() to get detailed + information about the kind of the error. + */ + bool Print(wxWindow * parent, wxPrintout * printout, + bool prompt=@true); + + /** + Invokes the print dialog. If successful (the user did not press Cancel + and no error occurred), a suitable device context will be returned + (otherwise @NULL is returned -- call + GetLastError() to get detailed + information about the kind of the error). + + The application must delete this device context to avoid a memory leak. + */ + wxDC* PrintDialog(wxWindow * parent); + + /** + Default error-reporting function. + */ + void ReportError(wxWindow * parent, wxPrintout * printout, + const wxString& message); + + /** + Invokes the print setup dialog. Note that the setup dialog is obsolete from + Windows 95, though retained for backward compatibility. + */ + bool Setup(wxWindow * parent); +}; + + +/** + @class wxPrintout + @wxheader{print.h} + + This class encapsulates the functionality of printing out an application + document. A new class must be derived and members overridden to respond to calls + such as OnPrintPage and HasPage and to render the print image onto an associated + wxDC. Instances of this class are passed to wxPrinter::Print or + to a wxPrintPreview object to initiate printing or previewing. + + Your derived wxPrintout is responsible for drawing both the preview image and + the printed page. If your windows' drawing routines accept an arbitrary DC as an + argument, you can re-use those routines within your wxPrintout subclass to draw + the printout image. You may also add additional drawing elements within your + wxPrintout subclass, like headers, footers, and/or page numbers. However, the + image on the printed page will often differ from the image drawn on the screen, + as will the print preview image -- not just in the presence of headers and + footers, but typically in scale. A high-resolution printer presents a much + larger drawing surface (i.e., a higher-resolution DC); a zoomed-out preview + image presents a much smaller drawing surface (lower-resolution DC). By using + the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX() within your + wxPrintout subclass to set the user scale and origin of the associated DC, you + can easily use a single drawing routine to draw on your application's windows, + to create the print preview image, and to create the printed paper image, and + achieve a common appearance to the preview image and the printed page. + + @library{wxbase} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", wxPrinterDC, + wxPrintDialog, wxPageSetupDialog, wxPrinter, wxPrintPreview +*/ +class wxPrintout : public wxObject +{ +public: + /** + Constructor. Pass an optional title argument - the current filename would be a + good idea. This will appear in the printing list + (at least in MSW) + */ + wxPrintout(const wxString& title = "Printout"); + + /** + Destructor. + */ + ~wxPrintout(); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that the given image size fits entirely within the page rectangle and the + origin is at the top left corner of the page rectangle. On MSW and Mac, the page + rectangle is the printable area of the page. On other platforms and PostScript + printing, the page rectangle is the entire paper. Use this if you want your + printed image as large as possible, but with the caveat that on some platforms, + portions of the image might be cut off at the edges. + */ + void FitThisSizeToPage(const wxSize& imageSize); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that the given image size fits entirely within the page margins set in the + given wxPageSetupDialogData object. This function provides the greatest + consistency across all platforms because it does not depend on having access to + the printable area of the paper. Note that on Mac, the native wxPageSetupDialog + does not let you set the page margins; you'll have to provide your own + mechanism, + or you can use the Mac-only class wxMacPageMarginsDialog. + */ + void FitThisSizeToPageMargins(const wxSize& imageSize, + const wxPageSetupDialogData& pageSetupData); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that the given image size fits entirely within the paper and the origin is at + the top left corner of the paper. Note that with most printers, the region + around the edges of the paper are not printable so that the edges of the image + could be cut off. Use this if you're managing your own page margins. + */ + void FitThisSizeToPaper(const wxSize& imageSize); + + /** + Returns the device context associated with the printout (given to the printout + at start of + printing or previewing). This will be a wxPrinterDC if printing under Windows + or Mac, + a wxPostScriptDC if printing on other platforms, and a wxMemoryDC if previewing. + */ +#define wxDC * GetDC() /* implementation is private */ + + /** + Return the rectangle corresponding to the page margins specified by the given + wxPageSetupDialogData object in the associated wxDC's logical coordinates for + the + current user scale and device origin. The page margins are specified + with respect to the edges of the paper on all platforms. + */ + wxRect GetLogicalPageMarginsRect(const wxPageSetupDialogData& pageSetupData); + + /** + Return the rectangle corresponding to the page in the associated wxDC's + logical coordinates for the current user scale and device origin. + On MSW and Mac, this will be the printable area of the paper. On other platforms + and PostScript printing, this will be the full paper rectangle. + */ + wxRect GetLogicalPageRect(); + + /** + Return the rectangle corresponding to the paper in the associated wxDC's + logical coordinates for the current user scale and device origin. + */ + wxRect GetLogicalPaperRect(); + + /** + Returns the number of pixels per logical inch of the printer device context. + Dividing the printer PPI by the screen PPI can give a suitable scaling factor + for drawing text onto the printer. Remember to multiply this by a scaling factor + to take the preview DC size into account. Or you can just use the + FitThisSizeToXXX() and MapScreenSizeToXXX routines below, which do most of the + scaling calculations for you. + */ + void GetPPIPrinter(int * w, int * h); + + /** + Returns the number of pixels per logical inch of the screen device context. + Dividing the printer PPI by the screen PPI can give a suitable scaling factor + for drawing text onto the printer. If you are doing your own scaling, remember + to multiply this by a scaling factor to take the preview DC size into account. + */ + void GetPPIScreen(int * w, int * h); + + /** + Called by the framework to obtain information from the application about minimum + and maximum page values that the user can select, and the required page range to + be printed. By default this returns 1, 32000 for the page minimum and maximum + values, and 1, 1 for the required page range. + + If @e minPage is zero, the page number controls in the print dialog will be + disabled. + */ + void GetPageInfo(int * minPage, int * maxPage, int * pageFrom, + int * pageTo); + + /** + Returns the size of the printer page in millimetres. + */ + void GetPageSizeMM(int * w, int * h); + + /** + Returns the size of the printer page in pixels, called the page rectangle. + The page rectangle has a top left corner at (0,0) and a bottom right corner at + (w,h). These values may not be the same as the values returned from + wxDC::GetSize; if the printout is being used for + previewing, a memory device context is used, which uses a bitmap size reflecting + the current preview zoom. The application must take this discrepancy into + account if previewing is to be supported. + */ + void GetPageSizePixels(int * w, int * h); + + /** + Returns the rectangle that corresponds to the entire paper in pixels, called the + paper rectangle. This distinction between paper rectangle and page + rectangle reflects the fact that most printers cannot print all the way to the + edge of the paper. The page rectangle is a rectangle whose top left corner is at + (0,0) and whose width and height are given by + wxDC::GetPageSizePixels. On MSW and Mac, + the page rectangle gives the printable area of the paper, while the paper + rectangle represents the entire paper, including non-printable borders. Thus, + the rectangle returned by GetPaperRectPixels will have a top left corner whose + coordinates are small negative numbers and the bottom right corner will have + values somewhat larger than the width and height given by + wxDC::GetPageSizePixels. On other + platforms and for PostScript printing, the paper is treated as if its entire + area were printable, so this function will return the same rectangle as the page + rectangle. + */ + wxRect GetPaperRectPixels(); + + /** + Returns the title of the printout + */ + wxString GetTitle(); + + /** + Should be overridden to return @true if the document has this page, or @false + if not. Returning @false signifies the end of the document. By default, + HasPage behaves as if the document has only one page. + */ + bool HasPage(int pageNum); + + /** + Returns @true if the printout is currently being used for previewing. + */ + bool IsPreview(); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that one screen pixel maps to one device pixel on the DC. That is, the user + scale is set to (1,1) and the device origin is set to (0,0). Use this if you + want to do your own scaling prior to calling wxDC drawing calls, for example, if + your underlying model is floating-point and you want to achieve maximum drawing + precision on high-resolution printers. (Note that while the underlying drawing + model of Mac OS X is floating-point, wxWidgets's drawing model scales from + integer + coordinates.) You can use the GetLogicalXXXRect() routines below to obtain the + paper rectangle, page rectangle, or page margins rectangle to perform your own + scaling. + */ + void MapScreenSizeToDevice(); + + /** + This sets the user scale of the wxDC assocated with this wxPrintout to the same + scale as MapScreenSizeToPaper() but sets + the logical origin to the top left corner of the page rectangle. + */ + void MapScreenSizeToPage(); + + /** + This sets the user scale of the wxDC assocated with this wxPrintout to the same + scale as + MapScreenSizeToPageMargins() but + sets the logical origin to the top left corner of the page margins specified by + the given wxPageSetupDialogData object. + */ + void MapScreenSizeToPageMargins(const wxPageSetupDialogData& pageSetupData); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that the printed page matches the screen size as closely as possible + and the logical origin is in the top left corner of the paper rectangle. + That is, + a 100-pixel object on screen should appear at the same size on the printed + page. (It + will, of course, be larger or smaller in the preview image, depending on the + zoom + factor.) Use this if you want WYSIWYG behavior, e.g., in a text editor. + */ + void MapScreenSizeToPaper(); + + /** + Shift the device origin by an amount specified in logical coordinates. + */ + void OffsetLogicalOrigin(wxCoord xoff, wxCoord yoff); + + /** + Called by the framework at the start of document printing. Return @false from + this function cancels the print job. OnBeginDocument is called once for every + copy printed. + + The base OnBeginDocument() @e must be called (and the return value + checked) from within the overridden function, since it calls wxDC::StartDoc. + */ + bool OnBeginDocument(int startPage, int endPage); + + /** + Called by the framework at the start of printing. OnBeginPrinting is called + once for every + print job (regardless of how many copies are being printed). + */ + void OnBeginPrinting(); + + /** + Called by the framework at the end of document printing. OnEndDocument + is called once for every copy printed. + + The base OnEndDocument() @e must be called + from within the overridden function, since it calls wxDC::EndDoc. + */ + void OnEndDocument(); + + /** + Called by the framework at the end of printing. OnEndPrinting + is called once for every print job (regardless of how many copies are being + printed). + */ + void OnEndPrinting(); + + /** + Called once by the framework before any other demands are made of the + wxPrintout object. This gives the object an opportunity to calculate the + number of pages in the document, for example. + */ + void OnPreparePrinting(); + + /** + Called by the framework when a page should be printed. Returning @false cancels + the print job. The application can use GetDC() to obtain a device + context to draw on. + */ + bool OnPrintPage(int pageNum); + + /** + Set the device origin of the associated wxDC so that the current logical point + becomes the new logical origin. + */ + void SetLogicalOrigin(wxCoord x, wxCoord y); +}; diff --git a/interface/printdlg.h b/interface/printdlg.h new file mode 100644 index 0000000000..3fcade0c1d --- /dev/null +++ b/interface/printdlg.h @@ -0,0 +1,124 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: printdlg.h +// Purpose: documentation for wxPrintDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPrintDialog + @wxheader{printdlg.h} + + This class represents the print and print setup common dialogs. + You may obtain a wxPrinterDC device context from + a successfully dismissed print dialog. + + @library{wxcore} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", @ref + overview_wxprintdialogoverview "wxPrintDialog Overview" +*/ +class wxPrintDialog : public wxDialog +{ +public: + /** + Constructor. Pass a parent window, and optionally a pointer to a block of print + data, which will be copied to the print dialog's print data. + + @sa wxPrintDialogData + */ + wxPrintDialog(wxWindow* parent, wxPrintDialogData* data = @NULL); + + /** + Destructor. If GetPrintDC() has @e not been called, + the device context obtained by the dialog (if any) will be deleted. + */ + ~wxPrintDialog(); + + /** + Returns the device context created by the print dialog, if any. + When this function has been called, the ownership of the device context + is transferred to the application, so it must then be deleted + explicitly. + */ + wxDC* GetPrintDC(); + + /** + Returns the @ref overview_wxprintdialogdata "print dialog data" associated with + the print dialog. + */ + wxPrintDialogData GetPrintDialogData(); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL + otherwise. After this function is called, a device context may + be retrievable using GetPrintDC(). + */ + int ShowModal(); +}; + + +/** + @class wxPageSetupDialog + @wxheader{printdlg.h} + + This class represents the page setup common dialog. In MSW, the page setup + dialog is standard from Windows 95 on, replacing the print setup dialog (which + is retained in Windows and wxWidgets for backward compatibility). On Windows 95 + and NT 4.0 and above, the page setup dialog is native to the windowing system, + otherwise it is emulated. + + The page setup dialog contains controls for paper size (A4, A5 etc.), + orientation (landscape or portrait), and controls for setting left, top, right + and bottom margin sizes in millimetres. + + On Macintosh, the native page setup dialog is used, which lets you select paper + size and orientation but it does not let you change the page margins. + + On other platforms, a generic dialog is used. + + When the dialog has been closed, you need to query the + wxPageSetupDialogData object associated with + the dialog. + + Note that the OK and Cancel buttons do not destroy the dialog; this must be done + by the application. + + @library{wxcore} + @category{printing} + + @seealso + @ref overview_printingoverview "Printing framework overview", wxPrintDialog, + wxPageSetupDialogData +*/ +class wxPageSetupDialog : public wxDialog +{ +public: + /** + Constructor. Pass a parent window, and optionally a pointer to a block of page + setup + data, which will be copied to the print dialog's internal data. + */ + wxPageSetupDialog(wxWindow* parent, + wxPageSetupDialogData* data = @NULL); + + /** + Destructor. + */ + ~wxPageSetupDialog(); + + /** + Returns the @ref overview_wxpagesetupdialogdata "page setup data" associated + with the dialog. + */ + wxPageSetupDialogData GetPageSetupData(); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL + otherwise. + */ + int ShowModal(); +}; diff --git a/interface/process.h b/interface/process.h new file mode 100644 index 0000000000..215414902f --- /dev/null +++ b/interface/process.h @@ -0,0 +1,258 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: process.h +// Purpose: documentation for wxProcess class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxProcess + @wxheader{process.h} + + The objects of this class are used in conjunction with the + wxExecute function. When a wxProcess object is passed to + wxExecute(), its wxProcess::OnTerminate virtual method + is called when the process terminates. This allows the program to be + (asynchronously) notified about the process termination and also retrieve its + exit status which is unavailable from wxExecute() in the case of + asynchronous execution. + + Please note that if the process termination notification is processed by the + parent, it is responsible for deleting the wxProcess object which sent it. + However, if it is not processed, the object will delete itself and so the + library users should only delete those objects whose notifications have been + processed (and call wxProcess::Detach for others). + + wxProcess also supports IO redirection of the child process. For this, you have + to call its wxProcess::Redirect method before passing it to + wxExecute. If the child process was launched successfully, + wxProcess::GetInputStream, + wxProcess::GetOutputStream and + wxProcess::GetErrorStream can then be used to retrieve + the streams corresponding to the child process standard output, input and + error output respectively. + + @b wxPerl note: In wxPerl this class has an additional @c Destroy method, + for explicit destruction. + + @library{wxbase} + @category{appmanagement} + + @seealso + wxExecute, @ref overview_sampleexec "exec sample" +*/ +class wxProcess : public wxEvtHandler +{ +public: + //@{ + /** + Constructs a process object. @e id is only used in the case you want to + use wxWidgets events. It identifies this object, or another window that will + receive the event. + + If the @e parent parameter is different from @NULL, it will receive + a wxEVT_END_PROCESS notification event (you should insert EVT_END_PROCESS + macro in the event table of the parent to handle it) with the given @e id. + + The second constructor creates an object without any associated parent (and + hence no id neither) but allows to specify the @e flags which can have the + value of @c wxPROCESS_DEFAULT or @c wxPROCESS_REDIRECT. Specifying the + former value has no particular effect while using the latter one is equivalent + to calling Redirect(). + + @param parent + The event handler parent. + + @param id + id of an event. + + @param flags + either wxPROCESS_DEFAULT or wxPROCESS_REDIRECT + */ + wxProcess(wxEvtHandler * parent = @NULL, int id = -1); + wxProcess(int flags); + //@} + + /** + Destroys the wxProcess object. + */ + ~wxProcess(); + + /** + Closes the output stream (the one connected to the stdin of the child + process). This function can be used to indicate to the child process that + there is no more data to be read - usually, a filter program will only + terminate when the input stream is closed. + */ + void CloseOutput(); + + /** + Normally, a wxProcess object is deleted by its parent when it receives the + notification about the process termination. However, it might happen that the + parent object is destroyed before the external process is terminated (e.g. a + window from which this external process was launched is closed by the user) + and in this case it @b should not delete the wxProcess object, but + @b should call Detach() instead. After the wxProcess object is detached + from its parent, no notification events will be sent to the parent and the + object will delete itself upon reception of the process termination + notification. + */ + void Detach(); + + /** + Returns @true if the given process exists in the system. + + @sa Kill(), @ref overview_sampleexec "Exec sample" + */ + static bool Exists(int pid); + + /** + Returns an input stream which corresponds to the standard error output (stderr) + of the child process. + */ + wxInputStream* GetErrorStream(); + + /** + It returns an input stream corresponding to the standard output stream of the + subprocess. If it is @NULL, you have not turned on the redirection. + See Redirect(). + */ + wxInputStream* GetInputStream(); + + /** + It returns an output stream correspoding to the input stream of the subprocess. + If it is @NULL, you have not turned on the redirection. + See Redirect(). + */ + wxOutputStream* GetOutputStream(); + + /** + Returns the process ID of the process launched by Open(). + */ + long GetPid(); + + /** + Returns @true if there is data to be read on the child process standard + error stream. + + @sa IsInputAvailable() + */ + bool IsErrorAvailable(); + + /** + Returns @true if there is data to be read on the child process standard + output stream. This allows to write simple (and extremely inefficient) + polling-based code waiting for a better mechanism in future wxWidgets versions. + + See the @ref overview_sampleexec "exec sample" for an example of using this + function. + + @sa IsInputOpened() + */ + bool IsInputAvailable(); + + /** + Returns @true if the child process standard output stream is opened. + */ + bool IsInputOpened(); + + /** + Send the specified signal to the given process. Possible signal values are: + @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning + under both Unix and Windows but all the other signals are equivalent to + @c wxSIGTERM under Windows. + + The @e flags parameter can be wxKILL_NOCHILDREN (the default), + or wxKILL_CHILDREN, in which case the child processes of this + process will be killed too. Note that under Unix, for wxKILL_CHILDREN + to work you should have created the process passing wxEXEC_MAKE_GROUP_LEADER. + + Returns the element of @c wxKillError enum: + + @sa Exists(), wxKill, @ref overview_sampleexec "Exec sample" + */ + static wxKillError Kill(int pid, wxSignal signal = wxSIGNONE, + int flags = wxKILL_NOCHILDREN); + + /** + It is called when the process with the pid + + @param pid finishes. + It raises a wxWidgets event when it isn't overridden. + + pid + The pid of the process which has just terminated. + + @param status + The exit code of the process. + */ + void OnTerminate(int pid, int status); + + /** + This static method replaces the standard @c popen() function: it launches + the process specified by the @e cmd parameter and returns the wxProcess + object which can be used to retrieve the streams connected to the standard + input, output and error output of the child process. + + If the process couldn't be launched, @NULL is returned. Note that in any + case the returned pointer should @b not be deleted, rather the process + object will be destroyed automatically when the child process terminates. This + does mean that the child process should be told to quit before the main program + exits to avoid memory leaks. + + @param cmd + The command to execute, including optional arguments. + + @param flags + The flags to pass to wxExecute. + NOTE: wxEXEC_SYNC should not be used. + + @returns A pointer to new wxProcess object or @NULL on error. + + @sa wxExecute + */ + static wxProcess * Open(const wxString& cmd, + int flags = wxEXEC_ASYNC); + + /** + Turns on redirection. wxExecute will try to open a couple of pipes + to catch the subprocess stdio. The caught input stream is returned by + GetOutputStream() as a non-seekable stream. The caught output stream is returned + by GetInputStream() as a non-seekable stream. + */ + void Redirect(); +}; + + +/** + @class wxProcessEvent + @wxheader{process.h} + + A process event is sent when a process is terminated. + + @library{wxbase} + @category{events} + + @seealso + wxProcess, @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxProcessEvent : public wxEvent +{ +public: + /** + Constructor. Takes a wxProcessObject or window id, a process id and an + exit status. + */ + wxProcessEvent(int id = 0, int pid = 0, int exitcode = 0); + + /** + Returns the exist status. + */ + int GetExitCode(); + + /** + Returns the process id. + */ + int GetPid(); +}; diff --git a/interface/progdlg.h b/interface/progdlg.h new file mode 100644 index 0000000000..68bd690936 --- /dev/null +++ b/interface/progdlg.h @@ -0,0 +1,121 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: progdlg.h +// Purpose: documentation for wxProgressDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxProgressDialog + @wxheader{progdlg.h} + + This class represents a dialog that shows a short message and a + progress bar. Optionally, it can display ABORT and SKIP buttons, + the elapsed, remaining and estimated time for the end of the progress. + + @beginStyleTable + @style{wxPD_APP_MODAL}: + Make the progress dialog modal. If this flag is not given, it is + only "locally" modal - that is the input to the parent window is + disabled, but not to the other ones. + @style{wxPD_AUTO_HIDE}: + Causes the progress dialog to disappear from screen as soon as the + maximum value of the progress meter has been reached. + @style{wxPD_SMOOTH}: + Causes smooth progress of the gauge control. + @style{wxPD_CAN_ABORT}: + This flag tells the dialog that it should have a "Cancel" button + which the user may press. If this happens, the next call to + Update() will return @false. + @style{wxPD_CAN_SKIP}: + This flag tells the dialog that it should have a "Skip" button + which the user may press. If this happens, the next call to + Update() will return @true in its skip parameter. + @style{wxPD_ELAPSED_TIME}: + This flag tells the dialog that it should show elapsed time (since + creating the dialog). + @style{wxPD_ESTIMATED_TIME}: + This flag tells the dialog that it should show estimated time. + @style{wxPD_REMAINING_TIME}: + This flag tells the dialog that it should show remaining time. + @endStyleTable + + @library{wxbase} + @category{cmndlg} +*/ +class wxProgressDialog : public wxDialog +{ +public: + /** + Constructor. Creates the dialog, displays it and disables user input + for other windows, or, if wxPD_APP_MODAL flag is not given, for its parent + window only. + + @param title + Dialog title to show in titlebar. + + @param message + Message displayed above the progress bar. + + @param maximum + Maximum value for the progress bar. + + @param parent + Parent window. + + @param style + The dialog style. See wxProgressDialog. + */ + wxProgressDialog(const wxString& title, const wxString& message, + int maximum = 100, + wxWindow * parent = @NULL, + int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL); + + /** + Destructor. Deletes the dialog and enables all top level windows. + */ + ~wxProgressDialog(); + + /** + Just like Update() but makes + the gauge control run in indeterminate mode (see wxGauge documentation), + sets the remaining and the estimated time labels (if present) to @c Unknown and + moves + the progress bar a bit to indicate that some progress was done. + */ + virtual bool Pulse(const wxString& newmsg = "", + bool * skip = @NULL); + + /** + Can be used to continue with the dialog, after the user had chosen + ABORT. + */ + void Resume(); + + /** + Updates the dialog, setting the progress bar to the new value and, if + given changes the message above it. Returns @true unless the Cancel button + has been pressed. + + If @false is returned, the application can either immediately destroy the + dialog + or ask the user for the confirmation and if the abort is not confirmed the + dialog may be resumed with Resume() function. + + @param value + The new value of the progress meter. It should be less than or + equal to the maximum value given to the constructor and the dialog is closed if + it is equal to the maximum. + + @param newmsg + The new messages for the progress dialog text, if it is + empty (which is the default) the message is not changed. + + @param skip + If "Skip" button was pressed since last + Update call, this is set to @true. + */ + virtual bool Update(int value, const wxString& newmsg = "", + bool * skip = @NULL); +}; diff --git a/interface/propdlg.h b/interface/propdlg.h new file mode 100644 index 0000000000..b4e652d0f3 --- /dev/null +++ b/interface/propdlg.h @@ -0,0 +1,189 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: propdlg.h +// Purpose: documentation for wxPropertySheetDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPropertySheetDialog + @wxheader{propdlg.h} + + This class represents a property sheet dialog: a tabbed dialog + for showing settings. It is optimized to show flat tabs + on PocketPC devices, and can be customized to use different + controllers instead of the default notebook style. + + To use this class, call wxPropertySheetDialog::Create from your own + Create function. Then call wxPropertySheetDialog::CreateButtons, and create + pages, adding them to the book control. + Finally call wxPropertySheetDialog::LayoutDialog. + + For example: + + @code + bool MyPropertySheetDialog::Create(...) + { + if (!wxPropertySheetDialog::Create(...)) + return @false; + + CreateButtons(wxOK|wxCANCEL|wxHELP); + + // Add page + wxPanel* panel = new wxPanel(GetBookCtrl(), ...); + GetBookCtrl()-AddPage(panel, wxT("General")); + + LayoutDialog(); + return @true; + } + @endcode + + If necessary, override CreateBookCtrl and AddBookCtrl to create and add a + different + kind of book control. You would then need to use two-step construction for the + dialog. + Or, change the style of book control by calling + wxPropertySheetDialog::SetSheetStyle + before calling Create. + + The dialogs sample shows this class being used with notebook and toolbook + controllers (for + Windows-style and Mac-style settings dialogs). + + To make pages of the dialog scroll when the display is too small to fit the + whole dialog, you can switch + layout adaptation on globally with wxDialog::EnableLayoutAdaptation or + per dialog with wxDialog::SetLayoutAdaptationMode. For more + about layout adaptation, see @ref overview_autoscrollingdialogs "Automatic + scrolling dialogs". + + @library{wxadv} + @category{managedwnd} +*/ +class wxPropertySheetDialog : public wxDialog +{ +public: + /** + Constructor. + */ + wxPropertySheetDialog(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, + const wxString& name = "dialogBox"); + + /** + Override this if you wish to add the book control in a way different from the + standard way (for example, using different spacing). + */ + virtual void AddBookCtrl(wxSizer* sizer); + + /** + Call this from your own Create function, before adding buttons and pages. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, + const wxString& name = "dialogBox"); + + /** + Override this if you wish to create a different kind of book control; by + default, the value + passed to SetSheetStyle() is used to determine the control. + The default behaviour is to create a notebook except on Smartphone, where a + choicebook is used. + */ + virtual wxBookCtrlBase* CreateBookCtrl(); + + /** + Call this to create the buttons for the dialog. This calls + wxDialog::CreateButtonSizer, and + the flags are the same. On PocketPC, no buttons are created. + */ + void CreateButtons(int flags=wxOK|wxCANCEL); + + /** + Returns the book control that will contain your settings pages. + */ + wxBookCtrlBase* GetBookCtrl(); + + /** + Returns the inner sizer that contains the book control and button sizer. + */ + wxSizer* GetInnerSizer(); + + /** + Returns the sheet style. See SetSheetStyle() for + permissable values. + */ + long GetSheetStyle(); + + /** + Call this to lay out the dialog. On PocketPC, this does nothing, since the + dialog will be shown + full-screen, and the layout will be done when the dialog receives a size event. + */ + void LayoutDialog(int centreFlags=wxBOTH); + + /** + Sets the book control used for the dialog. You will normally not need to use + this. + */ + void SetBookCtrl(wxBookCtrlBase* bookCtrl); + + /** + Sets the inner sizer that contains the book control and button sizer. You will + normally not need to use this. + */ + void SetInnerSizer(wxSizer* sizer); + + /** + You can customize the look and feel of the dialog by setting the sheet style. + It is + a bit list of the following values: + + + wxPROPSHEET_DEFAULT + + + Uses the default look and feel for the controller window, + normally a notebook except on Smartphone where a choice control is used. + + wxPROPSHEET_NOTEBOOK + + + Uses a notebook for the controller window. + + wxPROPSHEET_TOOLBOOK + + + Uses a toolbook for the controller window. + + wxPROPSHEET_CHOICEBOOK + + + Uses a choicebook for the controller window. + + wxPROPSHEET_LISTBOOK + + + Uses a listbook for the controller window. + + wxPROPSHEET_TREEBOOK + + + Uses a treebook for the controller window. + + wxPROPSHEET_SHRINKTOFIT + + + Shrinks the dialog window to fit the currently selected page (common behaviour + for + property sheets on Mac OS X). + */ + void SetSheetStyle(long style); +}; diff --git a/interface/protocol/ftp.h b/interface/protocol/ftp.h new file mode 100644 index 0000000000..1240399bea --- /dev/null +++ b/interface/protocol/ftp.h @@ -0,0 +1,252 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: protocol/ftp.h +// Purpose: documentation for wxFTP class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFTP + @headerfile ftp.h wx/protocol/ftp.h + + wxFTP can be used to establish a connection to an FTP server and perform all the + usual operations. Please consult the RFC 959 for more details about the FTP + protocol. + + To use a 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 wxFTP::SendCommand method. However to actually + transfer files you just get or give a stream to or from this class and the + actual data are read or written using the usual stream methods. + + Example of using wxFTP for file downloading: + + @code + wxFTP ftp; + + // if you don't use these lines anonymous login will be used + ftp.SetUser("user"); + ftp.SetPassword("password"); + + if ( !ftp.Connect("ftp.wxwindows.org") ) + { + wxLogError("Couldn't connect"); + return; + } + + ftp.ChDir("/pub"); + wxInputStream *in = ftp.GetInputStream("wxWidgets-4.2.0.tar.gz"); + if ( !in ) + { + wxLogError("Coudln't get file"); + } + else + { + size_t size = in-GetSize(); + char *data = new char[size]; + if ( !in-Read(data, size) ) + { + wxLogError("Read error"); + } + else + { + // file data is in the buffer + ... + } + + delete [] data; + delete in; + } + @endcode + + To upload a file you would do (assuming the connection to the server was opened + successfully): + + @code + wxOutputStream *out = ftp.GetOutputStream("filename"); + if ( out ) + { + out-Write(...); // your data + delete out; + } + @endcode + + @library{wxnet} + @category{net} + + @seealso + wxSocketBase +*/ +class wxFTP : public wxProtocol +{ +public: + /** + Default constructor. + */ +#define wxFTP() /* implementation is private */ + + /** + Destructor will close the connection if connected. + */ +#define ~wxFTP() /* implementation is private */ + + /** + Aborts the download currently in process, returns @true if ok, @false + if an error occurred. + */ + bool Abort(); + + /** + Change the current FTP working directory. + Returns @true if successful. + */ + bool ChDir(const wxString& dir); + + /** + Send the specified @e command to the FTP server. @e ret specifies + the expected result. + + @returns @true if the command has been sent successfully, else @false. + */ + bool CheckCommand(const wxString& command, char ret); + + /** + Returns @true if the given remote file exists, @false otherwise. + */ + bool FileExists(const wxString& filename); + + /** + The GetList function is quite low-level. It returns the list of the files in + the current directory. The list can be filtered using the @e wildcard string. + If @e 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: + But on Windows system, it will look like this: + Return value: @true if the file list was successfully retrieved, @false + otherwise. + + @sa GetFilesList() + */ + bool GetDirList(wxArrayString& files, + const wxString& wildcard = ""); + + /** + Returns the file size in bytes or -1 if the file doesn't exist or the size + couldn't be determined. Notice that this size can be approximative size only + and shouldn't be used for allocating the buffer in which the remote file is + copied, for example. + */ + int GetFileSize(const wxString& filename); + + /** + This function returns the computer-parsable list of the files in the current + directory (optionally only of the files matching the @e wildcard, all files + by default). This list always has the same format and contains one full + (including the directory path) file name per line. + + Return value: @true if the file list was successfully retrieved, @false + otherwise. + */ + bool GetFilesList(wxArrayString& files, + const wxString& wildcard = ""); + + /** + Creates a new input stream on the specified path. You can use all but the seek + functionality of 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. + + @returns Returns @NULL if an error occurred (it could be a network failure + or the fact that the file doesn't exist). + */ + wxInputStream * GetInputStream(const wxString& path); + + /** + Returns the last command result, i.e. the full server reply for the last + command. + */ + const wxString GetLastResult(); + + /** + Initializes an output stream to the specified @e file. The returned + stream has all but the seek functionality of wxStreams. When the user finishes + writing data, he has to delete the stream to close it. + + @returns An initialized write-only stream. + + @sa wxOutputStream + */ + wxOutputStream * GetOutputStream(const wxString& file); + + /** + Create the specified directory in the current FTP working directory. + Returns @true if successful. + */ + bool MkDir(const wxString& dir); + + /** + Returns the current FTP working directory. + */ +#define wxString Pwd() /* implementation is private */ + + /** + Rename the specified @e src element to @e dst. Returns @true if successful. + */ + bool Rename(const wxString& src, const wxString& dst); + + /** + Remove the specified directory from the current FTP working directory. + Returns @true if successful. + */ + bool RmDir(const wxString& dir); + + /** + Delete the file specified by @e path. Returns @true if successful. + */ + bool RmFile(const wxString& path); + + /** + Send the specified @e command to the FTP server and return the first + character of the return code. + */ + char SendCommand(const wxString& command); + + /** + Sets the transfer mode to ASCII. It will be used for the next transfer. + */ + bool SetAscii(); + + /** + Sets the transfer mode to binary (IMAGE). It will be used for the next transfer. + */ + bool SetBinary(); + + /** + If @e pasv is @true, passive connection to the FTP server is used. This is + the default as it works with practically all firewalls. If the server doesn't + support passive move, you may call this function with @false argument to use + active connection. + */ + void SetPassive(bool pasv); + + /** + Sets the password to be sent to the FTP server to be allowed to log in. + */ + void SetPassword(const wxString& passwd); + + /** + Sets the transfer mode to the specified one. It will be used for the next + transfer. + + If this function is never called, binary transfer mode is used by default. + */ + bool SetTransferMode(TransferMode mode); + + /** + Sets the user name to be sent to the FTP server to be allowed to log in. + */ + void SetUser(const wxString& user); +}; diff --git a/interface/protocol/http.h b/interface/protocol/http.h new file mode 100644 index 0000000000..0061782111 --- /dev/null +++ b/interface/protocol/http.h @@ -0,0 +1,66 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: protocol/http.h +// Purpose: documentation for wxHTTP class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHTTP + @headerfile http.h wx/protocol/http.h + + + @library{wxnet} + @category{net} + + @seealso + wxSocketBase, wxURL +*/ +class wxHTTP : public wxProtocol +{ +public: + /** + Returns the data attached with a field whose name is specified by @e header. + If the field doesn't exist, it will return an empty string and not a @NULL + string. + */ + wxString GetHeader(const wxString& header); + + /** + Creates a new input stream on the specified path. Notice that this stream is + unseekable, i.e. SeekI() and TellI() methods shouldn't be used. + + Note that you can still know the size of the file you are getting using + wxStreamBase::GetSize. However there is a + limitation: in HTTP protocol, the size is not always specified so sometimes + @c (size_t)-1 can returned ot indicate that the size is unknown. In such + case, you may want to use wxInputStream::LastRead + method in a loop to get the total size. + + @returns Returns the initialized stream. You must delete it yourself once + you don't use it anymore and this must be done before + the wxHTTP object itself is destroyed. The destructor + closes the network connection. The next time you will + try to get a file the network connection will have to + be reestablished, but you don't have to take care of + this since wxHTTP reestablishes it automatically. + + @sa wxInputStream + */ + wxInputStream * GetInputStream(const wxString& path); + + /** + Returns the HTTP response code returned by the server. Please refer to + RFC 2616 for the list of responses. + */ + int GetResponse(); + + /** + It sets data of a field to be sent during the next request to the HTTP server. + The field + name is specified by @e header and the content by @e h_data. + This is a low level function and it assumes that you know what you are doing. + */ + void SetHeader(const wxString& header, const wxString& h_data); +}; diff --git a/interface/protocol/protocol.h b/interface/protocol/protocol.h new file mode 100644 index 0000000000..6e810d047c --- /dev/null +++ b/interface/protocol/protocol.h @@ -0,0 +1,123 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: protocol/protocol.h +// Purpose: documentation for wxProtocol class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxProtocol + @headerfile protocol.h wx/protocol/protocol.h + + + @library{wxnet} + @category{FIXME} + + @seealso + wxSocketBase, wxURL +*/ +class wxProtocol : public wxSocketClient +{ +public: + /** + Abort the current stream. + + @returns Returns @true, if successful, else @false. + */ + bool Abort(); + + /** + Returns the type of the content of the last opened stream. It is a mime-type. + */ + wxString GetContentType(); + + /** + Returns the last occurred error. + + + @b wxPROTO_NOERR + + + No error. + + @b wxPROTO_NETERR + + + A generic network error occurred. + + @b wxPROTO_PROTERR + + + An error occurred during negotiation. + + @b wxPROTO_CONNERR + + + The client failed to connect the server. + + @b wxPROTO_INVVAL + + + Invalid value. + + @b wxPROTO_NOHNDLR + + + . + + @b wxPROTO_NOFILE + + + The remote file doesn't exist. + + @b wxPROTO_ABRT + + + Last action aborted. + + @b wxPROTO_RCNCT + + + An error occurred during reconnection. + + @b wxPROTO_STREAM + + + Someone tried to send a command during a transfer. + */ + wxProtocolError GetError(); + + /** + Creates a new input stream on the specified path. You can use all but seek + functionality of wxStream. Seek isn't available on all streams. For example, + HTTP or FTP streams don't deal with it. Other functions like StreamSize and + Tell aren't available for the moment for this sort of stream. + You will be notified when the EOF is reached by an error. + + @returns Returns the initialized stream. You will have to delete it + yourself once you don't use it anymore. The + destructor closes the network connection. + + @sa wxInputStream + */ + wxInputStream * GetInputStream(const wxString& path); + + /** + Tries to reestablish a previous opened connection (close and renegotiate + connection). + + @returns @true, if the connection is established, else @false. + */ + bool Reconnect(); + + /** + Sets the authentication password. It is mainly useful when FTP is used. + */ + void SetPassword(const wxString& user); + + /** + Sets the authentication user. It is mainly useful when FTP is used. + */ + void SetUser(const wxString& user); +}; diff --git a/interface/ptr_scpd.h b/interface/ptr_scpd.h new file mode 100644 index 0000000000..8264b0f116 --- /dev/null +++ b/interface/ptr_scpd.h @@ -0,0 +1,243 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ptr_scpd.h +// Purpose: documentation for wxScopedPtr class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxScopedPtr + @wxheader{ptr_scpd.h} + + This is a simple scoped smart pointer implementation that is similar to + the Boost smart pointers but rewritten to + use macros instead. + + Since wxWidgets 2.9.0 there is also a templated version of this class + with the same name. See wxScopedPtrT. + + A smart pointer holds a pointer to an object. The memory used by the object is + deleted when the smart pointer goes out of scope. This class is different from + the @c std::auto_ptr in so far as it doesn't provide copy constructor + nor assignment operator. This limits what you can do with it but is much less + surprizing than the "destructive copy'' behaviour of the standard class. + + @library{wxbase} + @category{FIXME} + + @seealso + wxScopedArray +*/ +class wxScopedPtr +{ +public: + /** + Creates the smart pointer with the given pointer or none if @NULL. On + compilers that support it, this uses the explicit keyword. + */ + explicit wxScopedPtr(type T = @NULL); + + /** + Destructor frees the pointer help by this object if it is not @NULL. + */ + ~wxScopedPtr(); + + /** + This operator gets the pointer stored in the smart pointer or returns @NULL if + there is none. + */ + const T* get(); + + /** + This operator works like the standard C++ pointer operator to return the object + being pointed to by the pointer. If the pointer is @NULL or invalid this will + crash. + */ + const T operator *(); + + /** + This operator works like the standard C++ pointer operator to return the pointer + in the smart pointer or @NULL if it is empty. + */ + const T* operator -(); + + /** + Returns the currently hold pointer and resets the smart pointer object to + @NULL. After a call to this function the caller is responsible for + deleting the pointer. + */ + T * release(); + + /** + Deletes the currently held pointer and sets it to @e p or to @NULL if no + arguments are specified. This function does check to make sure that the + pointer you are assigning is not the same pointer that is already stored. + */ + reset(T p = @NULL); + + /** + Swap the pointer inside the smart pointer with @e other. The pointer being + swapped must be of the same type (hence the same class name). + */ + swap(wxScopedPtr amp; other); +}; + + +/** + @class wxScopedArray + @wxheader{ptr_scpd.h} + + This is a simple scoped smart pointer array implementation that is similar to + the Boost smart pointers but rewritten to + use macros instead. + + @library{wxbase} + @category{FIXME} + + @seealso + wxScopedPtr +*/ +class wxScopedArray +{ +public: + /** + Creates the smart pointer with the given pointer or none if @NULL. On + compilers that support it, this uses the explicit keyword. + */ + wxScopedArray(type T = @NULL); + + /** + This operator gets the pointer stored in the smart pointer or returns @NULL if + there is none. + */ + const T* get(); + + /** + This operator acts like the standard [] indexing operator for C++ arrays. The + function does not do bounds checking. + */ + const T operator [](long int i); + + /** + Deletes the currently held pointer and sets it to 'p' or to @NULL if no + arguments are specified. This function does check to make sure that the + pointer you are assigning is not the same pointer that is already stored. + */ + reset(T p = @NULL); + + /** + Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped + must be of the same type (hence the same class name). + */ + swap(wxScopedPtr amp; ot); +}; + + +/** + @class wxScopedTiedPtr + @wxheader{ptr_scpd.h} + + This is a variation on the topic of wxScopedPtr. This + class is also a smart pointer but in addition it "ties'' the pointer value to + another variable. In other words, during the life time of this class the value + of that variable is set to be the same as the value of the pointer itself and + it is reset to its old value when the object is destroyed. This class is + especially useful when converting the existing code (which may already store + the pointers value in some variable) to the smart pointers. + + @library{wxbase} + @category{FIXME} +*/ +class wxScopedTiedPtr +{ +public: + /** + Constructor creates a smart pointer initialized with @e ptr and stores + @e ptr in the location specified by @e ppTie which must not be + @NULL. + */ + wxScopedTiedPtr(T ** ppTie, T * ptr); + + /** + Destructor frees the pointer help by this object and restores the value stored + at the tied location (as specified in the @ref ctor() constructor) + to the old value. + + Warning: this location may now contain an uninitialized value if it hadn't been + initialized previously, in particular don't count on it magically being + @NULL! + */ + ~wxScopedTiedPtr(); +}; + + +/** + @class wxScopedPtrT + @wxheader{ptr_scpd.h} + + A scoped pointer template class. It is the template version of + the old-style @ref overview_wxscopedptr "scoped pointer macros". + + @library{wxbase} + @category{FIXME} + + @seealso + wxSharedPtr, wxWeakRef +*/ +class wxScopedPtr +{ +public: + /** + Constructor. + */ + wxScopedPtrT(T * ptr = @NULL); + + /** + Destructor. + */ + ~wxScopedPtrT(); + + /** + Returns pointer to object or @NULL. + */ + T * get(); + + /** + Conversion to a boolean expression (in a variant which is not + convertable to anything but a boolean expression). If this class + contains a valid pointer it will return @e @true, if it contains + a @NULL pointer it will return @e @false. + */ + operator unspecified_bool_type(); + + /** + Returns a reference to the object. If the internal pointer is @NULL + this method will cause an assert in debug mode. + */ + T operator*(); + + /** + Returns pointer to object. If the pointer is @NULL this method will + cause an assert in debug mode. + */ + T * operator-(); + + /** + Releases the current pointer and returns it. + Afterwards the caller is responsible for deleting + the data contained in the scoped pointer before. + */ + T* release(); + + /** + Reset pointer to the value of @e ptr. The + previous pointer will be deleted. + */ + void reset(T * ptr = @NULL); + + /** + Swaps pointers. + */ + void swap(wxScopedPtr & ot); +}; diff --git a/interface/ptr_shrd.h b/interface/ptr_shrd.h new file mode 100644 index 0000000000..ec05ad0677 --- /dev/null +++ b/interface/ptr_shrd.h @@ -0,0 +1,85 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ptr_shrd.h +// Purpose: documentation for wxSharedPtr class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSharedPtrT + @wxheader{ptr_shrd.h} + + A smart pointer with non-intrusive reference counting. It is modeled + after @b boost::shared_ptr and can be used with STL containers + and wxVector - unlike @b std::auto_ptr + and wxScopedPtr. + + @library{wxbase} + @category{FIXME} + + @seealso + wxScopedPtr, wxWeakRef, wxObjectDataPtr +*/ +class wxSharedPtr +{ +public: + //@{ + /** + Constructors. + */ + wxSharedPtrT(T* ptr = @NULL); + wxSharedPtrT(const wxSharedPtr& tocopy); + //@} + + /** + Destructor. + */ + ~wxSharedPtrT(); + + /** + Returns pointer to its object or @NULL. + */ + T* get(); + + /** + Conversion to a boolean expression (in a variant which is not + convertable to anything but a boolean expression). If this class + contains a valid pointer it will return @e @true, if it contains + a @NULL pointer it will return @e @false. + */ + operator unspecified_bool_type(); + + /** + Returns a reference to the object. If the internal pointer is @NULL this + method will cause an assert in debug mode. + */ + T operator*(); + + /** + Returns pointer to its object or @NULL. + */ + T* operator-(); + + /** + Assignment operator. Releases any previously held pointer + and creates a reference to @e ptr. + */ + wxSharedPtrT& operator operator=(T * ptr); + + /** + Reset pointer to @e ptr. If the reference count of the + previously owned pointer was 1 it will be deleted. + */ + void reset(T * ptr = @NULL); + + /** + Returns @true if this is the only pointer pointing to its object. + */ + bool unique(); + + /** + Returns the number of pointers pointing to its object. + */ + long use_count(); +}; diff --git a/interface/quantize.h b/interface/quantize.h new file mode 100644 index 0000000000..6089cd2324 --- /dev/null +++ b/interface/quantize.h @@ -0,0 +1,59 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: quantize.h +// Purpose: documentation for wxQuantize class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxQuantize + @wxheader{quantize.h} + + Performs quantization, or colour reduction, on a wxImage. + + Functions in this class are static and so a wxQuantize object need not be + created. + + @library{wxcore} + @category{misc} +*/ +class wxQuantize : public wxObject +{ +public: + /** + Constructor. You do not need to construct a wxQuantize object since its + functions are static. + */ + wxQuantize(); + + /** + Converts input bitmap(s) into 8bit representation with custom palette. + + in_rows and out_rows are arrays [0..h-1] of pointer to rows + (in_rows contains w * 3 bytes per row, out_rows w bytes per row). + + Fills out_rows with indexes into palette (which is also stored into palette + variable). + */ + void DoQuantize(unsigned w, unsigned h, unsigned char** in_rows, + unsigned char** out_rows, + unsigned char* palette, + int desiredNoColours); + + //@{ + /** + This version sets a palette in the destination image so you don't + have to manage it yourself. + */ + bool Quantize(const wxImage& src, wxImage& dest, + wxPalette** pPalette, + int desiredNoColours = 236, + unsigned char** eightBitData = 0, + int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE|wxQUANTIZE_RETURN_8BIT_DATA); + bool Quantize(const wxImage& src, wxImage& dest, + int desiredNoColours = 236, + unsigned char** eightBitData = 0, + int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS|wxQUANTIZE_FILL_DESTINATION_IMAGE|wxQUANTIZE_RETURN_8BIT_DATA); + //@} +}; diff --git a/interface/radiobox.h b/interface/radiobox.h new file mode 100644 index 0000000000..9c224670e4 --- /dev/null +++ b/interface/radiobox.h @@ -0,0 +1,318 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: radiobox.h +// Purpose: documentation for wxRadioBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRadioBox + @wxheader{radiobox.h} + + A radio box item is used to select one of number of mutually exclusive + choices. It is displayed as a vertical column or horizontal row of + labelled buttons. + + @beginStyleTable + @style{wxRA_SPECIFY_ROWS}: + The major dimension parameter refers to the maximum number of rows. + @style{wxRA_SPECIFY_COLS}: + The major dimension parameter refers to the maximum number of + columns. + @style{wxRA_USE_CHECKBOX}: + Use of the checkbox controls instead of radio buttons (currently + supported only on PalmOS) + @endStyleTable + + @beginEventTable + @event{EVT_RADIOBOX(id\, func)}: + Process a wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton + is clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{radiobox.png} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", wxRadioButton, + wxCheckBox +*/ +class wxRadioBox : public wxControlWithItems +{ +public: + //@{ + /** + Constructor, creating and showing a radiobox. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param label + Label for the static box surrounding the radio buttons. + + @param pos + Window position. If wxDefaultPosition is specified then a default position + is chosen. + + @param size + Window size. If wxDefaultSize is specified then a default size is + chosen. + + @param n + Number of choices with which to initialize the radiobox. + + @param choices + An array of choices with which to initialize the radiobox. + + @param majorDimension + Specifies the maximum number of rows (if style contains wxRA_SPECIFY_ROWS) or + columns (if style contains wxRA_SPECIFY_COLS) for a two-dimensional + radiobox. + + @param style + Window style. See wxRadioBox. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxRadioBox(); + wxRadioBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = @NULL, + int majorDimension = 0, + long style = wxRA_SPECIFY_COLS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioBox"); + wxRadioBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& point, + const wxSize& size, + const wxArrayString& choices, + int majorDimension = 0, + long style = wxRA_SPECIFY_COLS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioBox"); + //@} + + /** + Destructor, destroying the radiobox item. + */ + ~wxRadioBox(); + + //@{ + /** + Creates the radiobox for two-step construction. See wxRadioBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = @NULL, + int majorDimension = 0, + long style = wxRA_SPECIFY_COLS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& point, + const wxSize& size, + const wxArrayString& choices, + int majorDimension = 0, + long style = wxRA_SPECIFY_COLS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioBox"); + //@} + + //@{ + /** + Enables or disables an individual button in the radiobox. + + @param enable + @true to enable, @false to disable. + + @param n + The zero-based button to enable or disable. + + @sa wxWindow::Enable + */ + virtual bool Enable(bool enable = @true); + virtual bool Enable(unsigned int n, bool enable = @true); + //@} + + /** + Finds a button matching the given string, returning the position if found, or + -1 if not found. + + @param string + The string to find. + */ + int FindString(const wxString& string); + + /** + Returns the number of columns in the radiobox. + */ + unsigned int GetColumnCount(); + + /** + Returns a radio box item under the point, a zero-based item index, or @c + wxNOT_FOUND if no item is under the point. + + @param pt + Point in client coordinates. + */ + int GetItemFromPoint(const wxPoint pt); + + /** + Returns the helptext associated with the specified @e item if any or @c + wxEmptyString. + + @param item + The zero-based item index. + + @sa SetItemHelpText() + */ + wxString GetItemHelpText(unsigned int item); + + /** + Returns the tooltip associated with the specified @e item if any or @NULL. + + @sa SetItemToolTip(), wxWindow::GetToolTip + */ + wxToolTip * GetItemToolTip(unsigned int item); + + /** + Returns the radiobox label. + + @param n + The zero-based button index. + + @sa SetLabel() + */ + wxString GetLabel(); + + /** + Returns the number of rows in the radiobox. + */ + unsigned int GetRowCount(); + + /** + Returns the zero-based position of the selected button. + */ + int GetSelection(); + + /** + Returns the label for the button at the given position. + + @param n + The zero-based button position. + */ + wxString GetString(unsigned int n); + + /** + Returns the selected string. + */ + wxString GetStringSelection(); + + /** + Returns @true if the item is enabled or @false if it was disabled using + @ref enable() "Enable(n, @false)". + + @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal + and always returns @true in the other ports. + + @param n + The zero-based button position. + */ + bool IsItemEnabled(unsigned int n); + + /** + Returns @true if the item is currently shown or @false if it was hidden + using + @ref show() "Show(n, @false)". + + Note that this function returns @true for an item which hadn't been hidden + even + if the entire radiobox is not currently shown. + + @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal + and always returns @true in the other ports. + + @param n + The zero-based button position. + */ + bool IsItemShown(unsigned int n); + + /** + Sets the helptext for an item. Empty string erases any existing helptext. + + @param item + The zero-based item index. + + @param helptext + The help text to set for the item. + + @sa GetItemHelpText() + */ + void SetItemHelpText(unsigned int item, const wxString& helptext); + + /** + Sets the tooltip text for the specified item in the radio group. + + @b Platform note: Currently only implemented in wxMSW and wxGTK2 and does + nothing in the other ports. + + @param item + Index of the item the tooltip will be shown for. + + @param text + Tooltip text for the item, the tooltip is removed if empty. + + @sa GetItemToolTip(), wxWindow::SetToolTip + */ + void SetItemToolTip(unsigned int item, const wxString& text); + + /** + Sets the radiobox label. + + @param label + The label to set. + + @param n + The zero-based button index. + */ + void SetLabel(const wxString& label); + + /** + Sets a button by passing the desired string position. This does not cause + a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted. + + @param n + The zero-based button position. + */ + void SetSelection(int n); + + /** + Sets the selection to a button by passing the desired string. This does not + cause + a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted. + + @param string + The label of the button to select. + */ + void SetStringSelection(const wxString& string); +}; diff --git a/interface/radiobut.h b/interface/radiobut.h new file mode 100644 index 0000000000..ef08ea723b --- /dev/null +++ b/interface/radiobut.h @@ -0,0 +1,123 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: radiobut.h +// Purpose: documentation for wxRadioButton class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRadioButton + @wxheader{radiobut.h} + + A radio button item is a button which usually denotes one of several mutually + exclusive options. It has a text label next to a (usually) round button. + + You can create a group of mutually-exclusive radio buttons by specifying @c + wxRB_GROUP for + the first in the group. The group ends when another radio button group is + created, or there are no more radio buttons. + + @beginStyleTable + @style{wxRB_GROUP}: + Marks the beginning of a new group of radio buttons. + @style{wxRB_SINGLE}: + In some circumstances, radio buttons that are not consecutive + siblings trigger a hang bug in Windows (only). If this happens, add + this style to mark the button as not belonging to a group, and + implement the mutually-exclusive group behaviour yourself. + @style{wxRB_USE_CHECKBOX}: + Use a checkbox button instead of radio button (currently supported + only on PalmOS). + @endStyleTable + + @beginEventTable + @event{EVT_RADIOBUTTON(id\, func)}: + Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED event, when the + radiobutton is clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{radiobutton.png} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", wxRadioBox, + wxCheckBox +*/ +class wxRadioButton : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a radio button. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param label + Label for the radio button. + + @param pos + Window position. If wxDefaultPosition is specified then a default position + is chosen. + + @param size + Window size. If wxDefaultSize is specified then a default size is + chosen. + + @param style + Window style. See wxRadioButton. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxRadioButton(); + wxRadioButton(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioButton"); + //@} + + /** + Destructor, destroying the radio button item. + */ + ~wxRadioButton(); + + /** + Creates the choice for two-step construction. See wxRadioButton() for + further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioButton"); + + /** + Returns @true if the radio button is depressed, @false otherwise. + */ + bool GetValue(); + + /** + Sets the radio button to selected or deselected status. This does not cause a + wxEVT_COMMAND_RADIOBUTTON_SELECTED event to get emitted. + + @param value + @true to select, @false to deselect. + */ + void SetValue(const bool value); +}; diff --git a/interface/recguard.h b/interface/recguard.h new file mode 100644 index 0000000000..1ced2af672 --- /dev/null +++ b/interface/recguard.h @@ -0,0 +1,97 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: recguard.h +// Purpose: documentation for wxRecursionGuardFlag class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRecursionGuardFlag + @wxheader{recguard.h} + + This is a completely opaque class which exists only to be used with + wxRecursionGuard, please see the example in that + class documentation. + + Please notice that wxRecursionGuardFlag object must be declared + @c static or the recursion would never be detected. + + @library{wxbase} + @category{FIXME} +*/ +class wxRecursionGuardFlag +{ +public: + +}; + + +/** + @class wxRecursionGuard + @wxheader{recguard.h} + + wxRecursionGuard is a very simple class which can be used to prevent reentrancy + problems in a function. It is not thread-safe and so should be used only in + single-threaded programs or in combination with some thread synchronization + mechanisms. + + wxRecursionGuard is always used together with the + wxRecursionGuardFlag like in this example: + + @code + void Foo() + { + static wxRecursionGuardFlag s_flag; + wxRecursionGuard guard(s_flag); + if ( guard.IsInside() ) + { + // don't allow reentrancy + return; + } + + ... + } + @endcode + + As you can see, wxRecursionGuard simply tests the flag value and sets it to + @true if it hadn't been already set. + wxRecursionGuard::IsInside allows testing the old flag + value. The advantage of using this class compared to directly manipulating the + flag is that the flag is always reset in the wxRecursionGuard destructor and so + you don't risk to forget to do it even if the function returns in an unexpected + way (for example because an exception has been thrown). + + @library{wxbase} + @category{FIXME} +*/ +class wxRecursionGuard +{ +public: + /** + A wxRecursionGuard object must always be initialized with a (static) + wxRecursionGuardFlag. The constructor saves the + value of the flag to be able to return the correct value from + IsInside(). + */ + wxRecursionGuard(wxRecursionGuardFlag& flag); + + /** + The destructor resets the flag value so that the function can be entered again + the next time. + + Note that it is not virtual and so this class is not meant to be derived from + (besides, there is absolutely no reason to do it anyhow). + */ + ~wxRecursionGuard(); + + /** + Returns @true if we're already inside the code block "protected'' by this + wxRecursionGuard (i.e. between this line and the end of current scope). Usually + the function using wxRecursionGuard takes some specific actions in such case + (may be simply returning) to prevent reentrant calls to itself. + + If this method returns @false, it is safe to continue. + */ + bool IsInside(); +}; diff --git a/interface/regex.h b/interface/regex.h new file mode 100644 index 0000000000..6ca1a209c7 --- /dev/null +++ b/interface/regex.h @@ -0,0 +1,148 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: regex.h +// Purpose: documentation for wxRegEx class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRegEx + @wxheader{regex.h} + + wxRegEx represents a regular expression. This class provides support + for regular expressions matching and also replacement. + + It is built on top of either the system library (if it has support + for POSIX regular expressions - which is the case of the most modern + Unices) or uses the built in Henry Spencer's library. Henry Spencer + would appreciate being given credit in the documentation of software + which uses his library, but that is not a requirement. + + Regular expressions, as defined by POSIX, come in two flavours: @e extended + and @e basic. The builtin library also adds a third flavour + of expression advanced, which is not available + when using the system library. + + Unicode is fully supported only when using the builtin library. + When using the system library in Unicode mode, the expressions and data + are translated to the default 8-bit encoding before being passed to + the library. + + On platforms where a system library is available, the default is to use + the builtin library for Unicode builds, and the system library otherwise. + It is possible to use the other if preferred by selecting it when building + the wxWidgets. + + @library{wxbase} + @category{data} + + @seealso + wxRegEx::ReplaceFirst +*/ +class wxRegEx +{ +public: + //@{ + /** + Create and compile the regular expression, use + IsValid() to test for compilation errors. + */ + wxRegEx(); + wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT); + //@} + + /** + dtor not virtual, don't derive from this class + */ + ~wxRegEx(); + + /** + Compile the string into regular expression, return @true if ok or @false + if string has a syntax error. + */ + bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT); + + //@{ + /** + Returns the part of string corresponding to the match where @e index is + interpreted as above. Empty string is returned if match failed + + May only be called after successful call to Matches() + and only if @c wxRE_NOSUB was @b not used in + Compile(). + */ + bool GetMatch(size_t* start, size_t* len, size_t index = 0); + not wxString GetMatch(const wxString& text, + size_t index = 0); + //@} + + /** + Returns the size of the array of matches, i.e. the number of bracketed + subexpressions plus one for the expression itself, or 0 on error. + + May only be called after successful call to Compile(). + and only if @c wxRE_NOSUB was @b not used. + */ + size_t GetMatchCount(); + + /** + Return @true if this is a valid compiled regular expression, @false + otherwise. + */ + bool IsValid(); + + //@{ + /** + Matches the precompiled regular expression against the string @e text, + returns @true if matches and @false otherwise. + + @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL. + + Some regex libraries assume that the text given is null terminated, while + others require the length be given as a separate parameter. Therefore for + maximum portability assume that @e text cannot contain embedded nulls. + + When the @e Matches(const wxChar *text, int flags = 0) form is used, + a @e wxStrlen() will be done internally if the regex library requires the + length. When using @e Matches() in a loop + the @e Matches(text, flags, len) form can be used instead, making it + possible to avoid a @e wxStrlen() inside the loop. + + May only be called after successful call to Compile(). + */ + bool Matches(const wxChar* text, int flags = 0); + bool Matches(const wxChar* text, int flags, size_t len); + bool Matches(const wxString& text, int flags = 0); + //@} + + /** + Replaces the current regular expression in the string pointed to by + @e text, with the text in @e replacement and return number of matches + replaced (maybe 0 if none found) or -1 on error. + + The replacement text may contain back references @c \number which will be + replaced with the value of the corresponding subexpression in the + pattern match. @c \0 corresponds to the entire match and @c is a + synonym for it. Backslash may be used to quote itself or @c character. + + @e maxMatches may be used to limit the number of replacements made, setting + it to 1, for example, will only replace first occurrence (if any) of the + pattern in the text while default value of 0 means replace all. + */ + int Replace(wxString* text, const wxString& replacement, + size_t maxMatches = 0); + + /** + Replace all occurrences: this is actually a synonym for + Replace(). + + @sa ReplaceFirst() + */ + int ReplaceAll(wxString* text, const wxString& replacement); + + /** + Replace the first occurrence. + */ + int ReplaceFirst(wxString* text, const wxString& replacement); +}; diff --git a/interface/region.h b/interface/region.h new file mode 100644 index 0000000000..f279e8966b --- /dev/null +++ b/interface/region.h @@ -0,0 +1,277 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: region.h +// Purpose: documentation for wxRegionIterator class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRegionIterator + @wxheader{region.h} + + This class is used to iterate through the rectangles in a region, + typically when examining the damaged regions of a window within an OnPaint call. + + To use it, construct an iterator object on the stack and loop through the + regions, testing the object and incrementing the iterator at the end of the + loop. + + See wxPaintEvent for an example of use. + + @library{wxcore} + @category{FIXME} + + @seealso + wxPaintEvent +*/ +class wxRegionIterator : public wxObject +{ +public: + //@{ + /** + Creates an iterator object given a region. + */ + wxRegionIterator(); + wxRegionIterator(const wxRegion& region); + //@} + + /** + An alias for GetHeight. + */ +#define wxCoord GetH() /* implementation is private */ + + /** + Returns the height value for the current region. + */ + wxCoord GetHeight(); + + /** + Returns the current rectangle. + */ + wxRect GetRect(); + + /** + An alias for GetWidth. + */ +#define wxCoord GetW() /* implementation is private */ + + /** + Returns the width value for the current region. + */ + wxCoord GetWidth(); + + /** + Returns the x value for the current region. + */ +#define wxCoord GetX() /* implementation is private */ + + /** + Returns the y value for the current region. + */ +#define wxCoord GetY() /* implementation is private */ + + /** + Returns @true if there are still some rectangles; otherwise returns @false. + */ + bool HaveRects(); + + //@{ + /** + Resets the iterator to the given region. + */ + void Reset(); + void Reset(const wxRegion& region); + //@} + + /** + Increment operator. Increments the iterator to the next region. + */ + void operator ++(); + + /** + Returns @true if there are still some rectangles; otherwise returns @false. + + You can use this to test the iterator object as if it were of type bool. + */ + operator bool(); +}; + + +/** + @class wxRegion + @wxheader{region.h} + + A wxRegion represents a simple or complex region on a device context or window. + + This class uses @ref overview_trefcount "reference counting and copy-on-write" + internally so that assignments between two instances of this class are very + cheap. You can therefore use actual objects instead of pointers without + efficiency problems. If an instance of this class is changed it will create + its own data internally so that other instances, which previously shared the + data using the reference counting, are not affected. + + @library{wxcore} + @category{data} + + @seealso + wxRegionIterator +*/ +class wxRegion : public wxGDIObject +{ +public: + //@{ + /** + Constructs a region using the non-transparent pixels of a bitmap. See + Union() for more details. + */ + wxRegion(); + wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight); + wxRegion(const wxRect& rect); + wxRegion(const wxRegion& region); + wxRegion(size_t n, const wxPoint points, + int fillStyle = wxWINDING_RULE); + wxRegion(const wxBitmap& bmp); + wxRegion(const wxBitmap& bmp, const wxColour& transColour, + int tolerance = 0); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxRegion(); + + /** + Clears the current region. + */ + void Clear(); + + //@{ + /** + Returns a value indicating whether the given rectangle is contained within the + region. + + @returns The return value is one of wxOutRegion, wxPartRegion and + wxInRegion. + */ + wxRegionContain Contains(long& x, long& y); + wxRegionContain Contains(const wxPoint& pt); + wxRegionContain Contains(long& x, long& y, + long& width, + long& height); + wxRegionContain Contains(const wxRect& rect); + //@} + + /** + Convert the region to a black and white bitmap with the white pixels + being inside the region. + */ + wxBitmap ConvertToBitmap(); + + //@{ + /** + Returns the outer bounds of the region. + */ + void GetBox(wxCoord& x, wxCoord& y, wxCoord& width, + wxCoord& height); + wxRect GetBox(); + //@} + + //@{ + /** + Finds the intersection of this region and another region. + + @returns @true if successful, @false otherwise. + + @remarks Creates the intersection of the two regions, that is, the parts + which are in both regions. The result is stored in + this region. + */ + bool Intersect(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + bool Intersect(const wxRect& rect); + bool Intersect(const wxRegion& region); + //@} + + /** + Returns @true if the region is empty, @false otherwise. + */ + bool IsEmpty(); + + /** + Returns @true if the region is equal to, i.e. covers the same area as, + another one. Note that if both this region and @e region are invalid, they + are considered to be equal. + */ + bool IsEqual(const wxRegion& region); + + //@{ + /** + Moves the region by the specified offsets in horizontal and vertical + directions. + + @returns @true if successful, @false otherwise (the region is unchanged + then). + */ + bool Offset(wxCoord x, wxCoord y); + bool Offset(const wxPoint& pt); + //@} + + //@{ + /** + Subtracts a region from this region. + + @returns @true if successful, @false otherwise. + + @remarks This operation combines the parts of 'this' region that are not + part of the second region. The result is stored in + this region. + */ + bool Subtract(const wxRect& rect); + bool Subtract(const wxRegion& region); + //@} + + //@{ + /** + Finds the union of this region and the non-transparent pixels of a + bitmap. Colour to be treated as transparent is specified in the + @e transColour argument, along with an + optional colour tolerance value. + + @returns @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region. The result is stored in this + region. + */ + bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + bool Union(const wxRect& rect); + bool Union(const wxRegion& region); + bool Union(const wxBitmap& bmp); + bool Union(const wxBitmap& bmp, const wxColour& transColour, + int tolerance = 0); + //@} + + //@{ + /** + Finds the Xor of this region and another region. + + @returns @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region, except for any overlapping + areas. The result is stored in this region. + */ + bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + bool Xor(const wxRect& rect); + bool Xor(const wxRegion& region); + //@} + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + void operator =(const wxRegion& region); +}; diff --git a/interface/renderer.h b/interface/renderer.h new file mode 100644 index 0000000000..8ca593fda6 --- /dev/null +++ b/interface/renderer.h @@ -0,0 +1,381 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: renderer.h +// Purpose: documentation for wxSplitterRenderParams class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSplitterRenderParams + @wxheader{renderer.h} + + This is just a simple @c struct used as a return value of + wxRendererNative::GetSplitterParams. + + It doesn't have any methods and all of its fields are constant and so can be + only examined but not modified. + + @library{wxbase} + @category{FIXME} +*/ +class wxSplitterRenderParams +{ +public: + /** + const wxCoord border + + The width of the border drawn by the splitter inside it, may be 0. + */ + + + /** + const bool isHotSensitive + + @true if the sash changes appearance when the mouse passes over it, @false + otherwise. + */ + + + /** + const wxCoord widthSash + + The width of the splitter sash. + */ +}; + + +/** + @class wxDelegateRendererNative + @wxheader{renderer.h} + + wxDelegateRendererNative allows reuse of renderers code by forwarding all the + wxRendererNative methods to the given object and + thus allowing you to only modify some of its methods -- without having to + reimplement all of them. + + Note that the "normal'', inheritance-based approach, doesn't work with the + renderers as it is impossible to derive from a class unknown at compile-time + and the renderer is only chosen at run-time. So suppose that you want to only + add something to the drawing of the tree control buttons but leave all the + other methods unchanged -- the only way to do it, considering that the renderer + class which you want to customize might not even be written yet when you write + your code (it could be written later and loaded from a DLL during run-time), is + by using this class. + + Except for the constructor, it has exactly the same methods as + wxRendererNative and their implementation is + trivial: they are simply forwarded to the real renderer. Note that the "real'' + renderer may, in turn, be a wxDelegateRendererNative as well and that there may + be arbitrarily many levels like this -- but at the end of the chain there must + be a real renderer which does the drawing. + + @library{wxcore} + @category{FIXME} +*/ +class wxDelegateRendererNative : public wxRendererNative +{ +public: + //@{ + /** + The default constructor does the same thing as the other one except that it + uses the @ref wxRendererNative::getgeneric "generic renderer" instead of the + user-specified @e 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) + @e rendererNative. + */ + wxDelegateRendererNative(); + wxDelegateRendererNative(wxRendererNative& rendererNative); + //@} + + /** + This class also provides all the virtual methods of + wxRendererNative, please refer to that class + documentation for the details. + */ + DrawXXX(...); +}; + + +/** + @class wxRendererNative + @wxheader{renderer.h} + + First, a brief introduction to wxRenderer and why it is needed. + + Usually wxWidgets uses the underlying low level GUI system to draw all the + controls - this is what we mean when we say that it is a "native'' framework. + However not all controls exist under all (or even any) platforms and in this + case wxWidgets provides a default, generic, implementation of them written in + wxWidgets itself. + + These controls don't have the native appearance if only the standard + line drawing and other graphics primitives are used, because the native + appearance is different under different platforms while the lines are always + drawn in the same way. + + This is why we have renderers: wxRenderer is a class which virtualizes the + drawing, i.e. it abstracts the drawing operations and allows you to draw say, a + button, without caring about exactly how this is done. Of course, as we + can draw the button differently in different renderers, this also allows us to + emulate the native look and feel. + + So the renderers work by exposing a large set of high-level drawing functions + which are used by the generic controls. There is always a default global + renderer but it may be changed or extended by the user, see + @ref overview_samplerender "Render sample". + + All drawing functions take some standard parameters: + + @e win is the window being drawn. It is normally not used and when + it is it should only be used as a generic wxWindow + (in order to get its low level handle, for example), but you should + not assume that it is of some given type as the same renderer + function may be reused for drawing different kinds of control. + @e dc is the wxDC to draw on. Only this device + context should be used for drawing. It is not necessary to restore + pens and brushes for it on function exit but, on the other hand, you + shouldn't assume that it is in any specific state on function entry: + the rendering functions should always prepare it. + @e rect the bounding rectangle for the element to be drawn. + @e flags the optional flags (none by default) which can be a + combination of the @c wxCONTROL_XXX constants below. + + Note that each drawing function restores the wxDC attributes if + it changes them, so it is safe to assume that the same pen, brush and colours + that were active before the call to this function are still in effect after it. + + @library{wxcore} + @category{gdi} +*/ +class wxRendererNative +{ +public: + /** + Virtual destructor as for any base class. + */ + ~wxRendererNative(); + + /** + Draw a check box (used by wxDataViewCtrl). + + @e flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or + @c wxCONTROL_UNDETERMINED bit set. + */ + void DrawCheckBox(wxWindow * win, wxDC& dc, const wxRect& rect, + int flags); + + /** + Draw a button like the one used by wxComboBox to show a + drop down window. The usual appearance is a downwards pointing arrow. + + @e flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set. + */ + void DrawComboBoxDropButton(wxWindow * win, wxDC& dc, + const wxRect& rect, + int flags); + + /** + Draw a drop down arrow that is suitable for use outside a combo box. Arrow will + have + transparent background. + + @e rect is not entirely filled by the arrow. Instead, you should use bounding + rectangle of a drop down button which arrow matches the size you need. + @e flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set. + */ + void DrawDropArrow(wxWindow * win, wxDC& dc, const wxRect& rect, + int flags); + + /** + Draw a focus rectangle using the specified rectangle. + wxListCtrl. The only supported flags is + @c wxCONTROL_SELECTED for items which are selected. + */ + void DrawFocusRect(wxWindow* win, wxDC& dc, const wxRect& rect, + int flags = 0); + + /** + Draw the header control button (used, for example, by + wxListCtrl). Depending on platforms the + @e flags parameter may support the @c wxCONTROL_SELECTED + @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits. + The @e sortArrow parameter can be one of + @c wxHDR_SORT_ICON_NONE, @c wxHDR_SORT_ICON_UP, or + @c wxHDR_SORT_ICON_DOWN. Additional values controlling the + drawing of a text or bitmap label can be passed in @e params. The + value returned is the optimal width to contain the the unabreviated + label text or bitmap, the sort arrow if present, and internal margins. + */ + int DrawHeaderButton(wxWindow* win, wxDC& dc, const wxRect& rect, + int flags = 0, + wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, + wxHeaderButtonParams* params = @NULL); + + /** + Draw a selection rectangle underneath the text as used e.g. in a + wxListCtrl. The supported @e flags are + @c wxCONTROL_SELECTED for items which are selected (e.g. often a blue + rectangle) and @c wxCONTROL_CURRENT for the item that has the focus + (often a dotted line around the item's text). @c wxCONTROL_FOCUSED may + be used to indicate if the control has the focus (othewise the the selection + rectangle is e.g. often grey and not blue). This may be ignored by the renderer + or deduced by the code directly from the @e win. + */ + void DrawItemSelectionRect(wxWindow* win, wxDC& dc, + const wxRect& rect, + int flags = 0); + + /** + Draw a blank push button that looks very similar to wxButton. + + @e flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or + @c wxCONTROL_ISDEFAULT bit set. + */ + void DrawPushButton(wxWindow * win, wxDC& dc, const wxRect& rect, + int flags); + + /** + Draw the border for sash window: this border must be such that the sash + drawn by @ref drawsplittersash() DrawSash blends into it + well. + */ + void DrawSplitterBorder(wxWindow* win, wxDC& dc, + const wxRect& rect, + int flags = 0); + + /** + Draw a sash. The @e orient parameter defines whether the sash should be + vertical or horizontal and how the @e position should be interpreted. + */ + void DrawSplitterSash(wxWindow* win, wxDC& dc, + const wxSize& size, + wxCoord position, + wxOrientation orient, + int flags = 0); + + /** + Draw the expanded/collapsed icon for a tree control item. To draw an expanded + button the @e flags parameter must contain @c wxCONTROL_EXPANDED bit. + */ + void DrawTreeItemButton(wxWindow* win, wxDC& dc, + const wxRect& rect, + int flags = 0); + + /** + Return the currently used renderer. + */ +#define wxRendererNative Get() /* implementation is private */ + + /** + Return the default (native) implementation for this platform -- this is also + the one used by default but this may be changed by calling + Set() in which case the return value of this + method may be different from the return value of Get(). + */ + wxRendererNative GetDefault(); + + /** + Return the generic implementation of the renderer. Under some platforms, this + is the default renderer implementation, others have platform-specific default + renderer which can be retrieved by calling GetDefault(). + */ + wxRendererNative GetGeneric(); + + /** + Returns the height of a header button, either a fixed platform height if + available, or a + generic height based on the window's font. + */ + int GetHeaderButtonHeight(const wxWindow* win); + + /** + Get the splitter parameters, see + wxSplitterRenderParams. + */ + wxSplitterRenderParams GetSplitterParams(const wxWindow* win); + + /** + This function is used for version checking: Load() + refuses to load any shared libraries implementing an older or incompatible + version. + + The implementation of this method is always the same in all renderers (simply + construct wxRendererVersion using the + @c wxRendererVersion::Current_XXX values), but it has to be in the derived, + not base, class, to detect mismatches between the renderers versions and so you + have to implement it anew in all renderers. + */ + wxRendererVersion GetVersion(); + + /** + Load the renderer from the specified DLL, the returned pointer must be + deleted by caller if not @NULL when it is not used any more. + + The @e name should be just the base name of the renderer and not the full + name of the DLL file which is constructed differently (using + wxDynamicLibrary::CanonicalizePluginName) + on different systems. + */ + wxRendererNative* Load(const wxString& name); + + /** + Set the renderer to use, passing @NULL reverts to using the default + renderer (the global renderer must always exist). + + Return the previous renderer used with Set() or @NULL if none. + */ +#define wxRendererNative* Set(wxRendererNative* renderer) /* implementation is private */ +}; + + +/** + @class wxRendererVersion + @wxheader{renderer.h} + + This simple struct represents the wxRendererNative + interface version and is only used as the return value of + wxRendererNative::GetVersion. + + The version has two components: the version itself and the age. If the main + program and the renderer have different versions they are never compatible with + each other because the version is only changed when an existing virtual + function is modified or removed. The age, on the other hand, is incremented + each time a new virtual method is added and so, at least for the compilers + using a common C++ object model, the calling program is compatible with any + renderer which has the age greater or equal to its age. This verification is + done by IsCompatible method. + + @library{wxbase} + @category{FIXME} +*/ +class wxRendererVersion +{ +public: + /** + Checks if the main program is compatible with the renderer having the version + @e ver, returns @true if it is and @false otherwise. + + This method is used by + wxRendererNative::Load to determine whether a + renderer can be used. + */ + static bool IsCompatible(const wxRendererVersion& ver); + + /** + const int age + + The age component. + */ + + + /** + const int version + + The version component. + */ +}; diff --git a/interface/richtext/richtextbuffer.h b/interface/richtext/richtextbuffer.h new file mode 100644 index 0000000000..22c4b12caa --- /dev/null +++ b/interface/richtext/richtextbuffer.h @@ -0,0 +1,1062 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextbuffer.h +// Purpose: documentation for wxRichTextBuffer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextBuffer + @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h + + This class represents the whole buffer associated with a wxRichTextCtrl. + + @library{wxrichtext} + @category{FIXME} + + @seealso + wxTextAttr, wxRichTextCtrl +*/ +class wxRichTextBuffer +{ +public: + //@{ + /** + Default constructors. + */ + wxRichTextBuffer(const wxRichTextBuffer& obj); + wxRichTextBuffer(); + //@} + + /** + Destructor. + */ + ~wxRichTextBuffer(); + + /** + Adds an event handler to the buffer's list of handlers. A buffer associated with + a contol has the control as the only event handler, but the application is free + to add more if further notification is required. All handlers are notified + of an event originating from the buffer, such as the replacement of a style + sheet + during loading. The buffer never deletes any of the event handlers, unless + RemoveEventHandler() is + called with @true as the second argument. + */ + bool AddEventHandler(wxEvtHandler* handler); + + /** + Adds a file handler. + */ + void AddHandler(wxRichTextFileHandler* handler); + + /** + Adds a paragraph of text. + */ + wxRichTextRange AddParagraph(const wxString& text); + + /** + Returns @true if the buffer is currently collapsing commands into a single + notional command. + */ + bool BatchingUndo(); + + /** + Begins using alignment. + */ + bool BeginAlignment(wxTextAttrAlignment alignment); + + /** + Begins collapsing undo/redo commands. Note that this may not work properly + if combining commands that delete or insert content, changing ranges for + subsequent actions. + + @e cmdName should be the name of the combined command that will appear + next to Undo and Redo in the edit menu. + */ + bool BeginBatchUndo(const wxString& cmdName); + + /** + Begin applying bold. + */ + bool BeginBold(); + + /** + Begins applying the named character style. + */ + bool BeginCharacterStyle(const wxString& characterStyle); + + /** + Begins using this font. + */ + bool BeginFont(const wxFont& font); + + /** + Begins using the given point size. + */ + bool BeginFontSize(int pointSize); + + /** + Begins using italic. + */ + bool BeginItalic(); + + /** + Begin using @e leftIndent for the left indent, and optionally @e leftSubIndent + for + the sub-indent. Both are expressed in tenths of a millimetre. + + The sub-indent is an offset from the left of the paragraph, and is used for all + but the + first line in a paragraph. A positive value will cause the first line to appear + to the left + of the subsequent lines, and a negative value will cause the first line to be + indented + relative to the subsequent lines. + */ + bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0); + + /** + Begins line spacing using the specified value. @e spacing is a multiple, where + 10 means single-spacing, + 15 means 1.5 spacing, and 20 means double spacing. The following constants are + defined for convenience: + */ + bool BeginLineSpacing(int lineSpacing); + + /** + Begins using a specified list style. Optionally, you can also pass a level and + a number. + */ + bool BeginListStyle(const wxString& listStyle, int level=1, + int number=1); + + /** + Begins a numbered bullet. This call will be needed for each item in the list, + and the + application should take care of incrementing the numbering. + + @e bulletNumber is a number, usually starting with 1. + + @e leftIndent and @e leftSubIndent are values in tenths of a millimetre. + + @e bulletStyle is a bitlist of the following values: + + + wxRichTextBuffer uses indentation to render a bulleted item. The left indent is + the distance between + the margin and the bullet. The content of the paragraph, including the first + line, starts + at leftMargin + leftSubIndent. So the distance between the left edge of the + bullet and the + left of the actual paragraph is leftSubIndent. + */ + bool BeginNumberedBullet(int bulletNumber, int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD); + + /** + Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing + in tenths of + a millimetre. + */ + bool BeginParagraphSpacing(int before, int after); + + /** + Begins applying the named paragraph style. + */ + bool BeginParagraphStyle(const wxString& paragraphStyle); + + /** + Begins a right indent, specified in tenths of a millimetre. + */ + bool BeginRightIndent(int rightIndent); + + /** + Begins applying a standard bullet, using one of the standard bullet names + (currently @c standard/circle or @c standard/square. + See BeginNumberedBullet() for an explanation of how indentation is used to + render the bulleted paragraph. + */ + bool BeginStandardBullet(const wxString& bulletName, + int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_STANDARD); + + /** + Begins using a specified style. + */ + bool BeginStyle(const wxTextAttr& style); + + /** + Begins suppressing undo/redo commands. The way undo is suppressed may be + implemented + differently by each command. If not dealt with by a command implementation, then + it will be implemented automatically by not storing the command in the undo + history + when the action is submitted to the command processor. + */ + bool BeginSuppressUndo(); + + /** + Begins applying a symbol bullet, using a character from the current font. See + BeginNumberedBullet() for + an explanation of how indentation is used to render the bulleted paragraph. + */ + bool BeginSymbolBullet(wxChar symbol, int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL); + + /** + Begins using the specified text foreground colour. + */ + bool BeginTextColour(const wxColour& colour); + + /** + Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a + character style to apply, + since it is common to mark a URL with a familiar style such as blue text with + underlining. + */ + bool BeginURL(const wxString& url, + const wxString& characterStyle = wxEmptyString); + + /** + Begins using underline. + */ + bool BeginUnderline(); + + /** + Returns @true if content can be pasted from the clipboard. + */ + bool CanPasteFromClipboard(); + + /** + Cleans up the file handlers. + */ + void CleanUpHandlers(); + + /** + Clears the buffer. + */ + void Clear(); + + //@{ + /** + Clears the list style from the given range, clearing list-related attributes + and applying any named paragraph style associated with each paragraph. + + @e flags is a bit list of the following: + + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + + See also SetListStyle(), PromoteList(), NumberList(). + */ + bool ClearListStyle(const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + bool ClearListStyle(const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + //@} + + /** + Clears the style stack. + */ + void ClearStyleStack(); + + /** + Clones the object. + */ + wxRichTextObject* Clone(); + + /** + Copies the given buffer. + */ + void Copy(const wxRichTextBuffer& obj); + + /** + Copy the given range to the clipboard. + */ + bool CopyToClipboard(const wxRichTextRange& range); + + /** + Submits a command to delete the given range. + */ + bool DeleteRangeWithUndo(const wxRichTextRange& range, + wxRichTextCtrl* ctrl); + + //@{ + /** + Dumps the contents of the buffer for debugging purposes. + */ + void Dump(); + void Dump(wxTextOutputStream& stream); + //@} + + /** + Ends alignment. + */ + bool EndAlignment(); + + /** + Ends all styles that have been started with a Begin... command. + */ + bool EndAllStyles(); + + /** + Ends collapsing undo/redo commands, and submits the combined command. + */ + bool EndBatchUndo(); + + /** + Ends using bold. + */ + bool EndBold(); + + /** + Ends using the named character style. + */ + bool EndCharacterStyle(); + + /** + Ends using a font. + */ + bool EndFont(); + + /** + Ends using a point size. + */ + bool EndFontSize(); + + /** + Ends using italic. + */ + bool EndItalic(); + + /** + Ends using a left indent. + */ + bool EndLeftIndent(); + + /** + Ends using a line spacing. + */ + bool EndLineSpacing(); + + /** + Ends using a specified list style. + */ + bool EndListStyle(); + + /** + Ends a numbered bullet. + */ + bool EndNumberedBullet(); + + /** + Ends paragraph spacing. + */ + bool EndParagraphSpacing(); + + /** + Ends applying a named character style. + */ + bool EndParagraphStyle(); + + /** + Ends using a right indent. + */ + bool EndRightIndent(); + + /** + Ends using a standard bullet. + */ + bool EndStandardBullet(); + + /** + Ends the current style. + */ + bool EndStyle(); + + /** + Ends suppressing undo/redo commands. + */ + bool EndSuppressUndo(); + + /** + Ends using a symbol bullet. + */ + bool EndSymbolBullet(); + + /** + Ends using a text foreground colour. + */ + bool EndTextColour(); + + /** + Ends applying a URL. + */ +#define bool EndURL() /* implementation is private */ + + /** + Ends using underline. + */ + bool EndUnderline(); + + //@{ + /** + Finds a handler by name. + */ + wxRichTextFileHandler* FindHandler(int imageType); + wxRichTextFileHandler* FindHandler(const wxString& extension, + int imageType); + wxRichTextFileHandler* FindHandler(const wxString& name); + //@} + + /** + Finds a handler by filename or, if supplied, type. + */ + wxRichTextFileHandler* FindHandlerFilenameOrType(const wxString& filename, + int imageType); + + /** + Gets the basic (overall) style. This is the style of the whole + buffer before further styles are applied, unlike the default style, which + only affects the style currently being applied (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + const wxTextAttr GetBasicStyle(); + + /** + Gets the collapsed command. + */ + wxRichTextCommand* GetBatchedCommand(); + + /** + Gets the command processor. A text buffer always creates its own command + processor when it is + initialized. + */ + wxCommandProcessor* GetCommandProcessor(); + + /** + Returns the current default style, affecting the style currently being applied + (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + const wxTextAttr GetDefaultStyle(); + + /** + Gets a wildcard incorporating all visible handlers. If @e types is present, + it will be filled with the file type corresponding to each filter. This can be + used to determine the type to pass to @ref getextwildcard() LoadFile given a + selected filter. + */ + wxString GetExtWildcard(bool combine = @false, bool save = @false, + wxArrayInt* types = @NULL); + + /** + Returns the list of file handlers. + */ + wxList GetHandlers(); + + /** + Returns the object to be used to render certain aspects of the content, such as + bullets. + */ + static wxRichTextRenderer* GetRenderer(); + + /** + Gets the attributes at the given position. + + This function gets the combined style - that is, the style you see on the + screen as a result + of combining base style, paragraph style and character style attributes. To get + the character + or paragraph style alone, use GetUncombinedStyle(). + */ + bool GetStyle(long position, wxTextAttr& style); + + /** + This function gets a style representing the common, combined attributes in the + given range. + Attributes which have different values within the specified range will not be + included the style + flags. + + The function is used to get the attributes to display in the formatting dialog: + the user + can edit the attributes common to the selection, and optionally specify the + values of further + attributes to be applied uniformly. + + To apply the edited attributes, you can use SetStyle() specifying + the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that + are different + from the @e combined attributes within the range. So, the user edits the + effective, displayed attributes + for the range, but his choice won't be applied unnecessarily to content. As an + example, + say the style for a paragraph specifies bold, but the paragraph text doesn't + specify a weight. The + combined style is bold, and this is what the user will see on-screen and in the + formatting + dialog. The user now specifies red text, in addition to bold. When applying with + SetStyle, the content font weight attributes won't be changed to bold because + this is already specified + by the paragraph. However the text colour attributes @e will be changed to + show red. + */ + bool GetStyleForRange(const wxRichTextRange& range, + wxTextAttr& style); + + /** + Returns the current style sheet associated with the buffer, if any. + */ + wxRichTextStyleSheet* GetStyleSheet(); + + /** + Get the size of the style stack, for example to check correct nesting. + */ + size_t GetStyleStackSize(); + + /** + Gets the attributes at the given position. + + This function gets the @e uncombined style - that is, the attributes associated + with the + paragraph or character content, and not necessarily the combined attributes you + see on the + screen. To get the combined attributes, use GetStyle(). + + If you specify (any) paragraph attribute in @e style's flags, this function + will fetch + the paragraph attributes. Otherwise, it will return the character attributes. + */ + bool GetUncombinedStyle(long position, wxTextAttr& style); + + /** + Finds the text position for the given position, putting the position in @e + textPosition if + one is found. @e pt is in logical units (a zero y position is + at the beginning of the buffer). + + The function returns one of the following values: + */ + int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition); + + /** + Initialisation. + */ + void Init(); + + /** + Initialises the standard handlers. Currently, only the plain text + loading/saving handler + is initialised by default. + */ + void InitStandardHandlers(); + + /** + Inserts a handler at the front of the list. + */ + void InsertHandler(wxRichTextFileHandler* handler); + + /** + Submits a command to insert the given image. + */ + bool InsertImageWithUndo(long pos, + const wxRichTextImageBlock& imageBlock, + wxRichTextCtrl* ctrl); + + /** + Submits a command to insert a newline. + */ + bool InsertNewlineWithUndo(long pos, wxRichTextCtrl* ctrl); + + /** + Submits a command to insert the given text. + */ + bool InsertTextWithUndo(long pos, const wxString& text, + wxRichTextCtrl* ctrl); + + /** + Returns @true if the buffer has been modified. + */ + bool IsModified(); + + //@{ + /** + Loads content from a file. + */ + bool LoadFile(wxInputStream& stream, + int type = wxRICHTEXT_TYPE_ANY); + bool LoadFile(const wxString& filename, + int type = wxRICHTEXT_TYPE_ANY); + //@} + + /** + Marks the buffer as modified or unmodified. + */ + void Modify(bool modify = @true); + + //@{ + /** + Numbers the paragraphs in the given range. Pass flags to determine how the + attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + + @e flags is a bit list of the following: + + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + See also SetListStyle(), PromoteList(), ClearListStyle(). + */ + bool NumberList(const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + bool Number(const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + //@} + + /** + Pastes the clipboard content to the buffer at the given position. + */ + bool PasteFromClipboard(long position); + + //@{ + /** + Promotes or demotes the paragraphs in the given range. A positive @e promoteBy + produces a smaller indent, and a negative number + produces a larger indent. Pass flags to determine how the attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + + @e flags is a bit list of the following: + + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + See also SetListStyle(), See also SetListStyle(), ClearListStyle(). + */ + bool PromoteList(int promoteBy, const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int listLevel = -1); + bool PromoteList(int promoteBy, const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int listLevel = -1); + //@} + + /** + Removes an event handler from the buffer's list of handlers, deleting the + object if @e deleteHandler is @true. + */ + bool RemoveEventHandler(wxEvtHandler* handler, + bool deleteHandler = @false); + + /** + Removes a handler. + */ + bool RemoveHandler(const wxString& name); + + /** + Clears the buffer, adds a new blank paragraph, and clears the command history. + */ + void ResetAndClearCommands(); + + //@{ + /** + Saves content to a file. + */ + bool SaveFile(wxOutputStream& stream, + int type = wxRICHTEXT_TYPE_ANY); + bool SaveFile(const wxString& filename, + int type = wxRICHTEXT_TYPE_ANY); + //@} + + /** + Sets the basic (overall) style. This is the style of the whole + buffer before further styles are applied, unlike the default style, which + only affects the style currently being applied (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + void SetBasicStyle(const wxTextAttr& style); + + /** + Sets the default style, affecting the style currently being applied (for + example, setting the default + style to bold will cause subsequently inserted text to be bold). + + This is not cumulative - setting the default style will replace the previous + default style. + */ + void SetDefaultStyle(const wxTextAttr& style); + + //@{ + /** + Sets the list attributes for the given range, passing flags to determine how + the attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + + @e flags is a bit list of the following: + + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + See also NumberList(), PromoteList(), ClearListStyle(). + */ + bool SetListStyle(const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + bool SetListStyle(const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + //@} + + /** + Sets @e renderer as the object to be used to render certain aspects of the + content, such as bullets. + You can override default rendering by deriving a new class from + wxRichTextRenderer or wxRichTextStdRenderer, + overriding one or more virtual functions, and setting an instance of the class + using this function. + */ + static void SetRenderer(wxRichTextRenderer* renderer); + + /** + Sets the attributes for the given range. Pass flags to determine how the + attributes are set. + + The end point of range is specified as the last character position of the span + of text. + So, for example, to set the style for a character at position 5, use the range + (5,5). + This differs from the wxRichTextCtrl API, where you would specify (5,6). + + @e flags may contain a bit list of the following values: + + wxRICHTEXT_SETSTYLE_NONE: no style flag. + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be + undoable. + wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied + if the + combined style at this point is already the style in question. + wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be + applied to paragraphs, + and not the content. This allows content styling to be preserved independently + from that of e.g. a named paragraph style. + wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be + applied to characters, + and not the paragraph. This allows content styling to be preserved + independently from that of e.g. a named paragraph style. + wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying + the new style. + wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags + are used in this operation. + */ + bool SetStyle(const wxRichTextRange& range, + const wxTextAttr& style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + + /** + Sets the current style sheet, if any. This will allow the application to use + named character and paragraph styles found in the style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Submit an action immediately, or delay it according to whether collapsing is on. + */ + bool SubmitAction(wxRichTextAction* action); + + /** + Returns @true if undo suppression is currently on. + */ + bool SuppressingUndo(); +}; + + +/** + @class wxRichTextFileHandler + @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h + + This is the base class for file handlers, for loading and/or saving content + associated with a wxRichTextBuffer. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextFileHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxRichTextFileHandler(const wxString& name = wxEmptyString, + const wxString& ext = wxEmptyString, + int type = 0); + + /** + Override this function and return @true if this handler can we handle @e + filename. By default, + this function checks the extension. + */ + bool CanHandle(const wxString& filename); + + /** + Override and return @true if this handler can load content. + */ + bool CanLoad(); + + /** + Override and return @true if this handler can save content. + */ + bool CanSave(); + + /** + Override to load content from @e stream into @e buffer. + */ + bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); + + /** + Override to save content to @e stream from @e buffer. + */ + bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); + + /** + Returns the encoding associated with the handler (if any). + */ + const wxString GetEncoding(); + + /** + Returns the extension associated with the handler. + */ + wxString GetExtension(); + + /** + Returns flags that change the behaviour of loading or saving. See the + documentation for each + handler class to see what flags are relevant for each handler. + */ + int GetFlags(); + + /** + Returns the name of the handler. + */ + wxString GetName(); + + /** + Returns the type of the handler. + */ + int GetType(); + + /** + Returns @true if this handler should be visible to the user. + */ + bool IsVisible(); + + //@{ + /** + Loads content from a stream or file. Not all handlers will implement file + loading. + */ + bool LoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); + bool LoadFile(wxRichTextBuffer* buffer, + const wxString& filename); + //@} + + //@{ + /** + Saves content to a stream or file. Not all handlers will implement file saving. + */ + bool SaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); + bool SaveFile(wxRichTextBuffer* buffer, + const wxString& filename); + //@} + + /** + Sets the encoding to use when saving a file. If empty, a suitable encoding is + chosen. + */ + void SetEncoding(const wxString& encoding); + + /** + Sets the default extension to recognise. + */ + void SetExtension(const wxString& ext); + + /** + Sets flags that change the behaviour of loading or saving. See the + documentation for each + handler class to see what flags are relevant for each handler. + + You call this function directly if you are using a file handler explicitly + (without + going through the text control or buffer LoadFile/SaveFile API). Or, you can + call the control or buffer's SetHandlerFlags function to set the flags that will + be used for subsequent load and save operations. + */ + void SetFlags(int flags); + + /** + Sets the name of the handler. + */ + void SetName(const wxString& name); + + /** + Sets the handler type. + */ + void SetType(int type); + + /** + Sets whether the handler should be visible to the user (via the application's + load and save + dialogs). + */ + void SetVisible(bool visible); +}; + + +/** + @class wxRichTextRange + @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h + + This class stores beginning and end positions for a range of data. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextRange +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextRange(long start, long end); + wxRichTextRange(const wxRichTextRange& range); + wxRichTextRange(); + //@} + + /** + Destructor. + */ + ~wxRichTextRange(); + + /** + Returns @true if the given position is within this range. Does not + match if the range is empty. + */ + bool Contains(long pos); + + /** + Converts the internal range, which uses the first and last character positions + of the range, + to the API-standard range, whose end is one past the last character in the + range. + In other words, one is added to the end position. + */ + wxRichTextRange FromInternal(); + + /** + Returns the end position. + */ + long GetEnd(); + + /** + Returns the length of the range. + */ + long GetLength(); + + /** + Returns the start of the range. + */ + long GetStart(); + + /** + Returns @true if this range is completely outside @e range. + */ + bool IsOutside(const wxRichTextRange& range); + + /** + Returns @true if this range is completely within @e range. + */ + bool IsWithin(const wxRichTextRange& range); + + /** + Limits this range to be within @e range. + */ + bool LimitTo(const wxRichTextRange& range); + + /** + Sets the end of the range. + */ + void SetEnd(long end); + + /** + Sets the range. + */ + void SetRange(long start, long end); + + /** + Sets the start of the range. + */ + void SetStart(long start); + + /** + Swaps the start and end. + */ + void Swap(); + + /** + Converts the API-standard range, whose end is one past the last character in + the range, + to the internal form, which uses the first and last character positions of the + range. + In other words, one is subtracted from the end position. + */ + wxRichTextRange ToInternal(); + + /** + Adds @e range to this range. + */ + wxRichTextRange operator+(const wxRichTextRange& range); + + /** + Subtracts @e range from this range. + */ + wxRichTextRange operator-(const wxRichTextRange& range); + + /** + Assigns @e range to this range. + */ + void operator=(const wxRichTextRange& range); + + /** + Returns @true if @e range is the same as this range. + */ + bool operator==(const wxRichTextRange& range); +}; diff --git a/interface/richtext/richtextctrl.h b/interface/richtext/richtextctrl.h new file mode 100644 index 0000000000..98360f957b --- /dev/null +++ b/interface/richtext/richtextctrl.h @@ -0,0 +1,1443 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextctrl.h +// Purpose: documentation for wxRichTextEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextEvent + @headerfile richtextctrl.h wx/richtext/richtextctrl.h + + This is the event class for wxRichTextCtrl notifications. + + @library{wxrichtext} + @category{events} +*/ +class wxRichTextEvent : public wxNotifyEvent +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextEvent(const wxRichTextEvent& event); + wxRichTextEvent(wxEventType commandType = wxEVT_@NULL, + int winid = 0); + //@} + + /** + Clones the event. + */ + wxEvent* Clone(); + + /** + Returns the character pressed, within a wxEVT_COMMAND_RICHTEXT_CHARACTER event. + */ + wxChar GetCharacter(); + + /** + Returns flags indicating modifier keys pressed. Possible values are + wxRICHTEXT_CTRL_DOWN, + wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + */ + int GetFlags(); + + /** + Returns the new style sheet. Can be used in a + wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. + */ + wxRichTextStyleSheet* GetNewStyleSheet(); + + /** + Returns the old style sheet. Can be used in a + wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. + */ + wxRichTextStyleSheet* GetOldStyleSheet(); + + /** + Returns the buffer position at which the event occured. + */ + long GetPosition(); + + /** + Gets the range for the current operation. + */ + wxRichTextRange GetRange(); + + /** + Sets the character variable. + */ + void SetCharacter(wxChar ch); + + /** + Sets flags indicating modifier keys pressed. Possible values are + wxRICHTEXT_CTRL_DOWN, + wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + */ + void SetFlags(int flags); + + /** + Sets the new style sheet variable. + */ + void SetNewStyleSheet(wxRichTextStyleSheet* sheet); + + /** + Sets the old style sheet variable. + */ + void SetOldStyleSheet(wxRichTextStyleSheet* sheet); + + /** + Sets the buffer position variable. + */ + void SetPosition(long pos); + + /** + Sets the range variable. + */ + void SetRange(const wxRichTextRange& range); +}; + + +/** + @class wxRichTextCtrl + @headerfile richtextctrl.h wx/richtext/richtextctrl.h + + wxRichTextCtrl provides a generic, ground-up implementation of a text control + capable of showing multiple styles and images. + + wxRichTextCtrl sends notification events: see wxRichTextEvent. + It also sends the standard wxTextCtrl events wxEVT_COMMAND_TEXT_ENTER and + wxEVT_COMMAND_TEXT_UPDATED, + and wxTextUrlEvent when URL content is clicked. + + For more information, see the @ref overview_wxrichtextctrloverview + "wxRichTextCtrl overview". + + @library{wxrichtext} + @category{ctrl} + @appearance{richtextctrl.png} +*/ +class wxRichTextCtrl +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextCtrl(); + wxRichTextCtrl(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxString& value = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxRE_MULTILINE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxTextCtrlNameStr); + //@} + + /** + Destructor. + */ + ~wxRichTextCtrl(); + + /** + Adds an image to the control's buffer. + */ + wxRichTextRange AddImage(const wxImage& image); + + /** + Adds a new paragraph of text to the end of the buffer. + */ + wxRichTextRange AddParagraph(const wxString& text); + + /** + Sets the insertion point to the end of the buffer and writes the text. + */ + void AppendText(const wxString& text); + + /** + Applies the given alignment to the selection (undoable). + + For alignment values, see wxTextAttr. + */ + bool ApplyAlignmentToSelection(wxTextAttrAlignment alignment); + + /** + Apples bold to the selection (undoable). + */ + bool ApplyBoldToSelection(); + + /** + Applies italic to the selection (undoable). + */ + bool ApplyItalicToSelection(); + + /** + Applies the given style to the selection. + */ + bool ApplyStyle(wxRichTextStyleDefinition* def); + + /** + Applies the style sheet to the buffer, matching paragraph styles in the sheet + against named styles + in the buffer. This might be useful if the styles have changed. If @e sheet is + @NULL, the + sheet set with SetStyleSheet is used. + + Currently this applies paragraph styles only. + */ + bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = @NULL); + + /** + Applies underline to the selection (undoable). + */ + bool ApplyUnderlineToSelection(); + + /** + Returns @true if undo commands are being batched. + */ + bool BatchingUndo(); + + /** + Begins using alignment + + For alignment values, see wxTextAttr. + */ + bool BeginAlignment(wxTextAttrAlignment alignment); + + /** + Starts batching undo history for commands. + */ + bool BeginBatchUndo(const wxString& cmdName); + + /** + Begins using bold. + */ + bool BeginBold(); + + /** + Begins using the named character style. + */ + bool BeginCharacterStyle(const wxString& characterStyle); + + /** + Begins using this font. + */ + bool BeginFont(const wxFont& font); + + /** + Begins using the given point size. + */ + bool BeginFontSize(int pointSize); + + /** + Begins using italic. + */ + bool BeginItalic(); + + /** + Begins applying a left indent and subindent in tenths of a millimetre. + + The sub-indent is an offset from the left of the paragraph, and is used for all + but the + first line in a paragraph. A positive value will cause the first line to appear + to the left + of the subsequent lines, and a negative value will cause the first line to be + indented + relative to the subsequent lines. + + wxRichTextBuffer uses indentation to render a bulleted item. The left indent is + the distance between + the margin and the bullet. The content of the paragraph, including the first + line, starts + at leftMargin + leftSubIndent. So the distance between the left edge of the + bullet and the + left of the actual paragraph is leftSubIndent. + */ + bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0); + + /** + Begins appling line spacing. @e spacing is a multiple, where 10 means + single-spacing, + 15 means 1.5 spacing, and 20 means double spacing. The following constants are + defined for convenience: + */ + bool BeginLineSpacing(int lineSpacing); + + /** + Begins using a specified list style. Optionally, you can also pass a level and + a number. + */ + bool BeginListStyle(const wxString& listStyle, int level=1, + int number=1); + + /** + Begins a numbered bullet. This call will be needed for each item in the list, + and the + application should take care of incrementing the numbering. + + @e bulletNumber is a number, usually starting with 1. + + @e leftIndent and @e leftSubIndent are values in tenths of a millimetre. + + @e bulletStyle is a bitlist of the following values: + + + wxRichTextBuffer uses indentation to render a bulleted item. The left indent is + the distance between + the margin and the bullet. The content of the paragraph, including the first + line, starts + at leftMargin + leftSubIndent. So the distance between the left edge of the + bullet and the + left of the actual paragraph is leftSubIndent. + */ + bool BeginNumberedBullet(int bulletNumber, int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD); + + /** + Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing + in tenths of + a millimetre. + */ + bool BeginParagraphSpacing(int before, int after); + + /** + Begins applying the named paragraph style. + */ + bool BeginParagraphStyle(const wxString& paragraphStyle); + + /** + Begins a right indent, specified in tenths of a millimetre. + */ + bool BeginRightIndent(int rightIndent); + + /** + Begins applying a style. + */ + bool BeginStyle(const wxTextAttr& style); + + /** + Starts suppressing undo history for commands. + */ + bool BeginSuppressUndo(); + + /** + Begins applying a symbol bullet, using a character from the current font. See + BeginNumberedBullet() for + an explanation of how indentation is used to render the bulleted paragraph. + */ + bool BeginSymbolBullet(wxChar symbol, int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL); + + /** + Begins using this colour. + */ + bool BeginTextColour(const wxColour& colour); + + /** + Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a + character style to apply, + since it is common to mark a URL with a familiar style such as blue text with + underlining. + */ + bool BeginURL(const wxString& url, + const wxString& characterStyle = wxEmptyString); + + /** + Begins using underlining. + */ + bool BeginUnderline(); + + /** + Returns @true if selected content can be copied to the clipboard. + */ + bool CanCopy(); + + /** + Returns @true if selected content can be copied to the clipboard and deleted. + */ + bool CanCut(); + + /** + Returns @true if selected content can be deleted. + */ + bool CanDeleteSelection(); + + /** + Returns @true if the clipboard content can be pasted to the buffer. + */ + bool CanPaste(); + + /** + Returns @true if there is a command in the command history that can be redone. + */ + bool CanRedo(); + + /** + Returns @true if there is a command in the command history that can be undone. + */ + bool CanUndo(); + + /** + Clears the buffer content, leaving a single empty paragraph. Cannot be undone. + */ + void Clear(); + + //@{ + /** + Clears the list style from the given range, clearing list-related attributes + and applying any named paragraph style associated with each paragraph. + + @e flags is a bit list of the following: + + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + + See also SetListStyle(), PromoteList(), NumberList(). + */ + bool ClearListStyle(const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + bool ClearListStyle(const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + //@} + + /** + Sends the event to the control. + */ + void Command(wxCommandEvent& event); + + /** + Copies the selected content (if any) to the clipboard. + */ + void Copy(); + + /** + Creates the underlying window. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxString& value = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxRE_MULTILINE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxTextCtrlNameStr); + + /** + Copies the selected content (if any) to the clipboard and deletes the selection. + This is undoable. + */ +#define void Cut() /* implementation is private */ + + /** + Deletes the content within the given range. + */ + bool Delete(const wxRichTextRange& range); + + /** + Deletes content if there is a selection, e.g. when pressing a key. + Returns the new caret position in @e newPos, or leaves it if there + was no action. This is undoable. + */ + bool DeleteSelectedContent(long* newPos = @NULL); + + /** + Deletes the content in the selection, if any. This is undoable. + */ + void DeleteSelection(); + + /** + Sets the buffer's modified status to @false, and clears the buffer's command + history. + */ + void DiscardEdits(); + + /** + Currently this simply returns @c wxSize(10, 10). + */ + wxSize DoGetBestSize(); + + /** + Ends alignment. + */ + bool EndAlignment(); + + /** + Ends application of all styles in the current style stack. + */ + bool EndAllStyles(); + + /** + Ends batching undo command history. + */ + bool EndBatchUndo(); + + /** + Ends using bold. + */ + bool EndBold(); + + /** + Ends application of a named character style. + */ + bool EndCharacterStyle(); + + /** + Ends using a font. + */ + bool EndFont(); + + /** + Ends using a point size. + */ + bool EndFontSize(); + + /** + Ends using italic. + */ + bool EndItalic(); + + /** + Ends left indent. + */ + bool EndLeftIndent(); + + /** + Ends line spacing. + */ + bool EndLineSpacing(); + + /** + Ends using a specified list style. + */ + bool EndListStyle(); + + /** + Ends application of a numbered bullet. + */ + bool EndNumberedBullet(); + + /** + Ends paragraph spacing. + */ + bool EndParagraphSpacing(); + + /** + Ends application of a named character style. + */ + bool EndParagraphStyle(); + + /** + Ends right indent. + */ + bool EndRightIndent(); + + /** + Ends the current style. + */ + bool EndStyle(); + + /** + Ends suppressing undo command history. + */ + bool EndSuppressUndo(); + + /** + Ends applying a symbol bullet. + */ + bool EndSymbolBullet(); + + /** + Ends applying a text colour. + */ + bool EndTextColour(); + + /** + Ends applying a URL. + */ +#define bool EndURL() /* implementation is private */ + + /** + End applying underlining. + */ + bool EndUnderline(); + + /** + Helper function for extending the selection, returning @true if the selection + was + changed. Selections are in caret positions. + */ + bool ExtendSelection(long oldPosition, long newPosition, + int flags); + + /** + Helper function for finding the caret position for the next word. Direction + is 1 (forward) or -1 (backwards). + */ + long FindNextWordPosition(int direction = 1); + + /** + Call this function to prevent refresh and allow fast updates, and then Thaw() to + refresh the control. + */ + void Freeze(); + + /** + Gets the basic (overall) style. This is the style of the whole + buffer before further styles are applied, unlike the default style, which + only affects the style currently being applied (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + const wxTextAttr GetBasicStyle(); + + //@{ + /** + Returns the buffer associated with the control. + */ + const wxRichTextBuffer GetBuffer(); + wxRichTextBuffer GetBuffer(); + //@} + + /** + Returns the current caret position. + */ + long GetCaretPosition(); + + /** + Returns the caret height and position for the given character position + */ + bool GetCaretPositionForIndex(long position, wxRect& rect); + + /** + Gets the command processor associated with the control's buffer. + */ + wxCommandProcessor* GetCommandProcessor(); + + /** + Returns the current default style, which can be used to change how subsequently + inserted + text is displayed. + */ + const wxTextAttr GetDefaultStyle(); + + /** + Gets the size of the buffer beyond which layout is delayed during resizing. + This optimizes sizing for large buffers. The default is 20000. + */ + long GetDelayedLayoutThreshold(); + + /** + Gets the current filename associated with the control. + */ + wxString GetFilename(); + + /** + Returns the first visible position in the current view. + */ + long GetFirstVisiblePosition(); + + /** + Returns flags that change the behaviour of loading or saving. See the + documentation for each + handler class to see what flags are relevant for each handler. + */ + int GetHandlerFlags(); + + /** + Returns the current insertion point. + */ + long GetInsertionPoint(); + + /** + Returns the last position in the buffer. + */ + wxTextPos GetLastPosition(); + + /** + Returns the length of the specified line in characters. + */ + int GetLineLength(long lineNo); + + /** + Returns the text for the given line. + */ + wxString GetLineText(long lineNo); + + /** + Transforms physical window position to logical (unscrolled) position. + */ + wxPoint GetLogicalPoint(const wxPoint& ptPhysical); + + /** + Returns the number of lines in the buffer. + */ + int GetNumberOfLines(); + + /** + Transforms logical (unscrolled) position to physical window position. + */ + wxPoint GetPhysicalPoint(const wxPoint& ptLogical); + + /** + Gets the text for the given range. + + The end point of range is specified as the last character position of the span + of text, plus one. + */ + wxString GetRange(long from, long to); + + /** + Returns the range of the current selection. + + The end point of range is specified as the last character position of the span + of text, plus one. + + If the return values @e from and @e to are the same, there is no selection. + */ + void GetSelection(long* from, long* to); + + /** + Returns the selection range in character positions. -1, -1 means no selection. + */ + const wxRichTextRange GetSelectionRange(); + + /** + Returns the text within the current selection range, if any. + */ + wxString GetStringSelection(); + + /** + Gets the attributes at the given position. + + This function gets the combined style - that is, the style you see on the + screen as a result + of combining base style, paragraph style and character style attributes. To get + the character + or paragraph style alone, use GetUncombinedStyle(). + */ + bool GetStyle(long position, wxTextAttr& style); + + /** + Gets the attributes common to the specified range. Attributes that differ in + value within the range will + not be included in @e style's flags. + */ + bool GetStyleForRange(const wxRichTextRange& range, + wxTextAttr& style); + + /** + Returns the style sheet associated with the control, if any. A style sheet + allows named + character and paragraph styles to be applied. + */ + wxRichTextStyleSheet* GetStyleSheet(); + + /** + Gets the attributes at the given position. + + This function gets the @e uncombined style - that is, the attributes associated + with the + paragraph or character content, and not necessarily the combined attributes you + see on the + screen. To get the combined attributes, use GetStyle(). + + If you specify (any) paragraph attribute in @e style's flags, this function + will fetch + the paragraph attributes. Otherwise, it will return the character attributes. + */ + bool GetUncombinedStyle(long position, wxTextAttr& style); + + /** + Returns the content of the entire control as a string. + */ + wxString GetValue(); + + /** + Internal helper function returning the line for the visible caret position. If + the caret is + shown at the very end of the line, it means the next character is actually + on the following line. So this function gets the line we're expecting to find + if this is the case. + */ + wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition); + + /** + Test if this whole range has character attributes of the specified kind. If any + of the attributes are different within the range, the test fails. You + can use this to implement, for example, bold button updating. @e style must have + flags indicating which attributes are of interest. + */ + bool HasCharacterAttributes(const wxRichTextRange& range, + const wxTextAttr& style); + + /** + Test if this whole range has paragraph attributes of the specified kind. If any + of the attributes are different within the range, the test fails. You + can use this to implement, for example, centering button updating. @e style + must have + flags indicating which attributes are of interest. + */ + bool HasParagraphAttributes(const wxRichTextRange& range, + const wxTextAttr& style); + + /** + Returns @true if there is a selection. + */ + bool HasSelection(); + + //@{ + /** + Finds the character at the given position in pixels. + + @e pt is in device coords (not adjusted for the client area origin nor for + scrolling). + */ + wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos); + wxTextCtrlHitTestResult HitTest(const wxPoint& pt, + wxTextCoord* col, + wxTextCoord* row); + //@} + + /** + Initialises the members of the control. + */ + void Init(); + + /** + Initialises the command event. + */ + void InitCommandEvent(wxCommandEvent& event); + + /** + Returns @true if the user has recently set the default style without moving + the caret, + and therefore the UI needs to reflect the default style and not the style at + the caret. + + Below is an example of code that uses this function to determine whether the UI + should show that the current style is bold. + See also SetAndShowDefaultStyle(). + */ + bool IsDefaultStyleShowing(); + + /** + Returns @true if the control is editable. + */ + bool IsEditable(); + + /** + Returns @true if Freeze has been called without a Thaw. + */ + bool IsFrozen(); + + /** + Returns @true if the buffer has been modified. + */ + bool IsModified(); + + /** + Returns @true if the control is multiline. + */ + bool IsMultiLine(); + + /** + Returns @true if the given position is visible on the screen. + */ + bool IsPositionVisible(long pos); + + /** + Returns @true if all of the selection is aligned according to the specified + flag. + */ + bool IsSelectionAligned(wxTextAttrAlignment alignment); + + /** + Returns @true if all of the selection is bold. + */ + bool IsSelectionBold(); + + /** + Returns @true if all of the selection is italic. + */ + bool IsSelectionItalics(); + + /** + Returns @true if all of the selection is underlined. + */ + bool IsSelectionUnderlined(); + + /** + Returns @true if the control is single-line. Currently wxRichTextCtrl does not + support single-line editing. + */ + bool IsSingleLine(); + + /** + Helper function implementing keyboard navigation. + */ + bool KeyboardNavigate(int keyCode, int flags); + + /** + Lays out the buffer, which must be done before certain operations, such as + setting the caret position. This function should not normally be required by the + application. + */ + bool LayoutContent(bool onlyVisibleRect = @false); + + /** + Inserts a line break at the current insertion point. A line break forces + wrapping within a paragraph, and + can be introduced by using this function, by appending the wxChar value @b + wxRichTextLineBreakChar to text content, + or by typing Shift-Return. + */ + bool LineBreak(); + + /** + Loads content into the control's buffer using the given type. If the specified + type + is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. + + This function looks for a suitable wxRichTextFileHandler object. + */ + bool LoadFile(const wxString& file, + int type = wxRICHTEXT_TYPE_ANY); + + /** + Marks the buffer as modified. + */ + void MarkDirty(); + + /** + Move the caret to the given character position. + */ + bool MoveCaret(long pos, bool showAtLineStart = @false); + + /** + Move the caret one visual step forward: this may mean setting a flag + and keeping the same position if we're going from the end of one line + to the start of the next, which may be the exact same caret position. + */ + void MoveCaretBack(long oldPosition); + + /** + Move the caret one visual step forward: this may mean setting a flag + and keeping the same position if we're going from the end of one line + to the start of the next, which may be the exact same caret position. + */ + void MoveCaretForward(long oldPosition); + + /** + Moves the caret down. + */ + bool MoveDown(int noLines = 1, int flags = 0); + + /** + Moves to the end of the buffer. + */ + bool MoveEnd(int flags = 0); + + /** + Moves to the start of the buffer. + */ + bool MoveHome(int flags = 0); + + /** + Moves left. + */ + bool MoveLeft(int noPositions = 1, int flags = 0); + + /** + Moves right. + */ + bool MoveRight(int noPositions = 1, int flags = 0); + + /** + Moves to the end of the line. + */ + bool MoveToLineEnd(int flags = 0); + + /** + Moves to the start of the line. + */ + bool MoveToLineStart(int flags = 0); + + /** + Moves to the end of the paragraph. + */ + bool MoveToParagraphEnd(int flags = 0); + + /** + Moves to the start of the paragraph. + */ + bool MoveToParagraphStart(int flags = 0); + + /** + Moves up. + */ + bool MoveUp(int noLines = 1, int flags = 0); + + /** + Inserts a new paragraph at the current insertion point. See also LineBreak(). + */ + bool Newline(); + + //@{ + /** + Numbers the paragraphs in the given range. Pass flags to determine how the + attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + + @e flags is a bit list of the following: + + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + See also SetListStyle(), PromoteList(), ClearListStyle(). + */ + bool NumberList(const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + bool Number(const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + //@} + + /** + Standard handler for the wxID_CLEAR command. + */ + void OnClear(wxCommandEvent& event); + + /** + Shows a standard context menu with undo, redo, cut, copy, paste, clear, and + select all commands. + */ + void OnContextMenu(wxContextMenuEvent& event); + + /** + Standard handler for the wxID_COPY command. + */ + void OnCopy(wxCommandEvent& event); + + /** + Standard handler for the wxID_CUT command. + */ + void OnCut(wxCommandEvent& event); + + /** + Loads the first dropped file. + */ + void OnDropFiles(wxDropFilesEvent& event); + + /** + Standard handler for the wxID_PASTE command. + */ + void OnPaste(wxCommandEvent& event); + + /** + Standard handler for the wxID_REDO command. + */ + void OnRedo(wxCommandEvent& event); + + /** + Standard handler for the wxID_SELECTALL command. + */ + void OnSelectAll(wxCommandEvent& event); + + /** + Standard handler for the wxID_PASTE command. + */ + void OnUndo(wxCommandEvent& event); + + /** + Standard update handler for the wxID_CLEAR command. + */ + void OnUpdateClear(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_COPY command. + */ + void OnUpdateCopy(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_CUT command. + */ + void OnUpdateCut(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_PASTE command. + */ + void OnUpdatePaste(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_REDO command. + */ + void OnUpdateRedo(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_SELECTALL command. + */ + void OnUpdateSelectAll(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_UNDO command. + */ + void OnUpdateUndo(wxUpdateUIEvent& event); + + /** + Moves one or more pages down. + */ + bool PageDown(int noPages = 1, int flags = 0); + + /** + Moves one or more pages up. + */ + bool PageUp(int noPages = 1, int flags = 0); + + /** + Paints the background. + */ + void PaintBackground(wxDC& dc); + + /** + Pastes content from the clipboard to the buffer. + */ + void Paste(); + + /** + Internal function to position the visible caret according to the current caret + position. + */ + void PositionCaret(); + + /** + Converts a text position to zero-based column and line numbers. + */ + bool PositionToXY(long pos, long* x, long* y); + + //@{ + /** + Promotes or demotes the paragraphs in the given range. A positive @e promoteBy + produces a smaller indent, and a negative number + produces a larger indent. Pass flags to determine how the attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + + @e flags is a bit list of the following: + + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + See also SetListStyle(), See also SetListStyle(), ClearListStyle(). + */ + bool PromoteList(int promoteBy, const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int listLevel = -1); + bool PromoteList(int promoteBy, const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int listLevel = -1); + //@} + + /** + Redoes the current command. + */ + void Redo(); + + /** + Removes the content in the specified range. + */ + void Remove(long from, long to); + + /** + Replaces the content in the specified range with the string specified by @e + value. + */ + void Replace(long from, long to, const wxString& value); + + /** + Saves the buffer content using the given type. If the specified type + is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. + + This function looks for a suitable wxRichTextFileHandler object. + */ + bool SaveFile(const wxString& file = wxEmptyString, + int type = wxRICHTEXT_TYPE_ANY); + + /** + Scrolls @e position into view. This function takes a caret position. + */ + bool ScrollIntoView(long position, int keyCode); + + /** + Selects all the text in the buffer. + */ + void SelectAll(); + + /** + Cancels any selection. + */ + void SelectNone(); + + /** + Sets @e attr as the default style and tells the control that the UI should + reflect + this attribute until the user moves the caret. + + See also IsDefaultStyleShowing(). + */ + void SetAndShowDefaultStyle(const wxTextAttr& attr); + + /** + Sets the basic (overall) style. This is the style of the whole + buffer before further styles are applied, unlike the default style, which + only affects the style currently being applied (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + void SetBasicStyle(const wxTextAttr& style); + + /** + The caret position is the character position just before the caret. + A value of -1 means the caret is at the start of the buffer. + */ + void SetCaretPosition(long position, + bool showAtLineStart = @false); + + /** + Sets the current default style, which can be used to change how subsequently + inserted + text is displayed. + */ + bool SetDefaultStyle(const wxTextAttr& style); + + /** + Sets the default style to the style under the cursor. + */ + bool SetDefaultStyleToCursorStyle(); + + /** + Sets the size of the buffer beyond which layout is delayed during resizing. + This optimizes sizing for large buffers. The default is 20000. + */ + void SetDelayedLayoutThreshold(long threshold); + + /** + Makes the control editable, or not. + */ + void SetEditable(bool editable); + + /** + Sets the current filename. + */ + void SetFilename(const wxString& filename); + + /** + Sets the font, and also the basic and default attributes (see + wxRichTextCtrl::SetDefaultStyle). + */ + bool SetFont(const wxFont& font); + + /** + Sets flags that change the behaviour of loading or saving. See the + documentation for each + handler class to see what flags are relevant for each handler. + */ + void SetHandlerFlags(int flags); + + /** + Sets the insertion point. + */ + void SetInsertionPoint(long pos); + + /** + Sets the insertion point to the end of the text control. + */ + void SetInsertionPointEnd(); + + //@{ + /** + Sets the list attributes for the given range, passing flags to determine how + the attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + + @e flags is a bit list of the following: + + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @e listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + See also NumberList(), PromoteList(), ClearListStyle(). + */ + bool SetListStyle(const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + bool SetListStyle(const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + //@} + + /** + Sets the selection to the given range. + + The end point of range is specified as the last character position of the span + of text, plus one. + So, for example, to set the selection for a character at position 5, use the + range (5,6). + */ + void SetSelection(long from, long to); + + /** + Sets the selection to the given range. + + The end point of range is specified as the last character position of the span + of text, plus one. + So, for example, to set the selection for a character at position 5, use the + range (5,6). + */ + void SetSelectionRange(const wxRichTextRange& range); + + //@{ + /** + Sets the attributes for the given range. + + The end point of range is specified as the last character position of the span + of text, plus one. + So, for example, to set the style for a character at position 5, use the range + (5,6). + */ + bool SetStyle(const wxRichTextRange& range, + const wxTextAttr& style); + bool SetStyle(long start, long end, const wxTextAttr& style); + //@} + + //@{ + /** + Sets the attributes for the given range, passing flags to determine how the + attributes are set. + + The end point of range is specified as the last character position of the span + of text, plus one. + So, for example, to set the style for a character at position 5, use the range + (5,6). + + @e flags may contain a bit list of the following values: + + wxRICHTEXT_SETSTYLE_NONE: no style flag. + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be + undoable. + wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied + if the + combined style at this point is already the style in question. + wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be + applied to paragraphs, + and not the content. This allows content styling to be preserved independently + from that of e.g. a named paragraph style. + wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be + applied to characters, + and not the paragraph. This allows content styling to be preserved + independently from that of e.g. a named paragraph style. + wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying + the new style. + wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags + are used in this operation. + */ + bool SetStyleEx(const wxRichTextRange& range, + const wxTextAttr& style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + bool SetStyleEx(long start, long end, + const wxTextAttr& style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + //@} + + /** + Sets the style sheet associated with the control. A style sheet allows named + character and paragraph styles to be applied. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Replaces existing content with the given text. + */ + void SetValue(const wxString& value); + + /** + A helper function setting up scrollbars, for example after a resize. + */ + void SetupScrollbars(bool atTop = @false); + + /** + Scrolls the buffer so that the given position is in view. + */ + void ShowPosition(long pos); + + /** + Returns @true if undo history suppression is on. + */ + bool SuppressingUndo(); + + /** + Call this function to end a Freeze and refresh the display. + */ + void Thaw(); + + /** + Undoes the command at the top of the command history, if there is one. + */ + void Undo(); + + /** + Moves a number of words to the left. + */ + bool WordLeft(int noWords = 1, int flags = 0); + + /** + Move a nuber of words to the right. + */ + bool WordRight(int noWords = 1, int flags = 0); + + //@{ + /** + Write a bitmap or image at the current insertion point. Supply an optional type + to use + for internal and file storage of the raw data. + */ + bool WriteImage(const wxString& filename, int bitmapType); + bool WriteImage(const wxRichTextImageBlock& imageBlock); + bool WriteImage(const wxBitmap& bitmap, + int bitmapType = wxBITMAP_TYPE_PNG); + bool WriteImage(const wxImage& image, + int bitmapType = wxBITMAP_TYPE_PNG); + //@} + + /** + Writes text at the current position. + */ + void WriteText(const wxString& text); + + /** + Translates from column and line number to position. + */ + long XYToPosition(long x, long y); +}; diff --git a/interface/richtext/richtextformatdlg.h b/interface/richtext/richtextformatdlg.h new file mode 100644 index 0000000000..c602462ec3 --- /dev/null +++ b/interface/richtext/richtextformatdlg.h @@ -0,0 +1,257 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextformatdlg.h +// Purpose: documentation for wxRichTextFormattingDialogFactory class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextFormattingDialogFactory + @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h + + This class provides pages for wxRichTextFormattingDialog, and allows other + customization of the dialog. + A default instance of this class is provided automatically. If you wish to + change the behaviour of the + formatting dialog (for example add or replace a page), you may derive from this + class, + override one or more functions, and call the static function + wxRichTextFormattingDialog::SetFormattingDialogFactory. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextFormattingDialogFactory : public wxObject +{ +public: + /** + Constructor. + */ + wxRichTextFormattingDialogFactory(); + + /** + Destructor. + */ + ~wxRichTextFormattingDialogFactory(); + + /** + Creates the main dialog buttons. + */ + virtual bool CreateButtons(wxRichTextFormattingDialog* dialog); + + /** + Creates a page, given a page identifier. + */ + virtual wxPanel* CreatePage(int page, wxString& title, + wxRichTextFormattingDialog* dialog); + + /** + Creates all pages under the dialog's book control, also calling AddPage. + */ + virtual bool CreatePages(long pages, + wxRichTextFormattingDialog* dialog); + + /** + Enumerate all available page identifiers. + */ + virtual int GetPageId(int i); + + /** + Gets the number of available page identifiers. + */ + virtual int GetPageIdCount(); + + /** + Gets the image index for the given page identifier. + */ + virtual int GetPageImage(int id); + + /** + Set the property sheet style, called at the start of + wxRichTextFormattingDialog::Create. + */ + virtual bool SetSheetStyle(wxRichTextFormattingDialog* dialog); + + /** + Invokes help for the dialog. + */ + virtual bool ShowHelp(int page, + wxRichTextFormattingDialog* dialog); +}; + + +/** + @class wxRichTextFormattingDialog + @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h + + This dialog allows the user to edit a character and/or paragraph style. + + In the constructor, specify the pages that will be created. Use GetStyle + to retrieve the common style for a given range, and then use ApplyStyle + to apply the user-selected formatting to a control. For example: + + @code + wxRichTextRange range; + if (m_richTextCtrl-HasSelection()) + range = m_richTextCtrl-GetSelectionRange(); + else + range = wxRichTextRange(0, m_richTextCtrl-GetLastPosition()+1); + + int pages = + wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING|wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS; + + wxRichTextFormattingDialog formatDlg(pages, this); + formatDlg.GetStyle(m_richTextCtrl, range); + + if (formatDlg.ShowModal() == wxID_OK) + { + formatDlg.ApplyStyle(m_richTextCtrl, range); + } + @endcode + + @library{wxrichtext} + @category{cmndlg} +*/ +class wxRichTextFormattingDialog : public wxPropertySheetDialog +{ +public: + //@{ + /** + Constructors. + + @param flags + The pages to show. + + @param parent + The dialog's parent. + + @param id + The dialog's identifier. + + @param title + The dialog's caption. + + @param pos + The dialog's position. + + @param size + The dialog's size. + + @param style + The dialog's window style. + */ + wxRichTextFormattingDialog(long flags, wxWindow* parent); + const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE) + wxRichTextFormattingDialog(); + //@} + + /** + Destructor. + */ + ~wxRichTextFormattingDialog(); + + /** + Apply attributes to the given range, only changing attributes that need to be + changed. + */ + bool ApplyStyle(wxRichTextCtrl* ctrl, + const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE); + + /** + Creation: see @ref overview_wxrichtextformattingdialog "the constructor" for + details about the parameters. + */ + bool Create(long flags, wxWindow* parent, const wxString& title, + wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& sz = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE); + + //@{ + /** + Gets the attributes being edited. + */ + const wxTextAttr GetAttributes(); + wxTextAttr GetAttributes(); + //@} + + /** + Helper for pages to get the top-level dialog. + */ + wxRichTextFormattingDialog* GetDialog(wxWindow* win); + + /** + Helper for pages to get the attributes. + */ + wxTextAttr* GetDialogAttributes(wxWindow* win); + + /** + Helper for pages to get the style. + */ + wxRichTextStyleDefinition* GetDialogStyleDefinition(wxWindow* win); + + /** + Returns the object to be used to customize the dialog and provide pages. + */ + wxRichTextFormattingDialogFactory* GetFormattingDialogFactory(); + + /** + Returns the image list associated with the dialog, used for example if showing + the dialog as a toolbook. + */ + wxImageList* GetImageList(); + + /** + Gets common attributes from the given range and calls SetAttributes. Attributes + that do not have common values in the given range + will be omitted from the style's flags. + */ + bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range); + + /** + Gets the associated style definition, if any. + */ + wxRichTextStyleDefinition* GetStyleDefinition(); + + /** + Gets the associated style sheet, if any. + */ + wxRichTextStyleSheet* GetStyleSheet(); + + /** + Sets the attributes to be edited. + */ + void SetAttributes(const wxTextAttr& attr); + + /** + Sets the formatting factory object to be used for customization and page + creation. + It deletes the existing factory object. + */ + void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory); + + /** + Sets the image list associated with the dialog's property sheet. + */ + void SetImageList(wxImageList* imageList); + + /** + Sets the attributes and optionally updates the display, if @e update is @true. + */ + bool SetStyle(const wxTextAttr& style, bool update = @true); + + /** + Sets the style definition and optionally update the display, if @e update is @c + @true. + */ + bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef, + wxRichTextStyleSheet* sheet, + bool update = @true); + + /** + Updates the display. + */ + bool UpdateDisplay(); +}; diff --git a/interface/richtext/richtexthtml.h b/interface/richtext/richtexthtml.h new file mode 100644 index 0000000000..b95c1ba073 --- /dev/null +++ b/interface/richtext/richtexthtml.h @@ -0,0 +1,112 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtexthtml.h +// Purpose: documentation for wxRichTextHTMLHandler class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextHTMLHandler + @headerfile richtexthtml.h wx/richtext/richtexthtml.h + + Handles HTML output (only) for wxRichTextCtrl content. + + The most flexible way to use this class is to create a temporary object and call + its functions directly, rather than use wxRichTextBuffer::SaveFile or + wxRichTextCtrl::SaveFile. + + Image handling requires a little extra work from the application, to choose an + appropriate image format for the target HTML viewer and to clean up the + temporary images + later. If you are planning to load the HTML into a standard web browser, you can + specify the handler flag wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_BASE64 (the default) + and no extra work is required: the images will be written with the HTML. + + However, if you want wxHTML compatibility, you will need to use + wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY + or wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES. In this case, you must either call + wxRichTextHTMLHandler::DeleteTemporaryImages before + the next load operation, or you must store the image + locations and delete them yourself when appropriate. You can call + wxRichTextHTMLHandler::GetTemporaryImageLocations to + get the array of temporary image names. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextHTMLHandler : public wxRichTextFileHandler +{ +public: + /** + , @b const wxString&@e ext = wxT("html"), @b int@e type = wxRICHTEXT_TYPE_HTML) + + Constructor. + */ + wxRichTextHTMLHandler(); + + /** + Clears the image locations generated by the last operation. + */ + void ClearTemporaryImageLocations(); + + //@{ + /** + Delete the in-memory or temporary files generated by the last operation. This + is a static + function that can be used to delete the saved locations from an earlier + operation, + for example after the user has viewed the HTML file. + */ + bool DeleteTemporaryImages(); + bool DeleteTemporaryImages(int flags, + const wxArrayString& imageLocations); + //@} + + /** + Saves the buffer content to the HTML stream. + */ + bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); + + /** + Returns the mapping for converting point sizes to HTML font sizes. + */ + wxArrayInt GetFontSizeMapping(); + + /** + Returns the directory used to store temporary image files. + */ + const wxString GetTempDir(); + + /** + Returns the image locations for the last operation. + */ + const wxArrayString GetTemporaryImageLocations(); + + /** + Reset the file counter, in case, for example, the same names are required each + time + */ + void SetFileCounter(int counter); + + /** + Sets the mapping for converting point sizes to HTML font sizes. + There should be 7 elements, one for each HTML font size, each element + specifying the maximum point size for that + HTML font size. + + For example: + */ + void SetFontSizeMapping(const wxArrayInt& fontSizeMapping); + + /** + Sets the directory for storing temporary files. If empty, the system + temporary directory will be used. + */ + void SetTempDir(const wxString& tempDir); + + /** + Sets the list of image locations generated by the last operation. + */ + void SetTemporaryImageLocations(const wxArrayString& locations); +}; diff --git a/interface/richtext/richtextprint.h b/interface/richtext/richtextprint.h new file mode 100644 index 0000000000..ec68d4a039 --- /dev/null +++ b/interface/richtext/richtextprint.h @@ -0,0 +1,396 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextprint.h +// Purpose: documentation for wxRichTextHeaderFooterData class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextHeaderFooterData + @headerfile richtextprint.h wx/richtext/richtextprint.h + + + This class represents header and footer data to be passed to the + wxRichTextPrinting and + wxRichTextPrintout classes. + + Headers and footers can be specified independently for odd, even or both page + sides. Different text can be specified + for left, centre and right locations on the page, and the font and text colour + can also + be specified. You can specify the following keywords in header and footer text, + which will + be substituted for the actual values during printing and preview. + + @DATE@: the current date. + @PAGESCNT@: the total number of pages. + @PAGENUM@: the current page number. + @TIME@: the current time. + @TITLE@: the title of the document, as passed to the wxRichTextPrinting or + wxRichTextLayout constructor. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextHeaderFooterData : public wxObject +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextHeaderFooterData(); + wxRichTextHeaderFooterData(const wxRichTextHeaderFooterData& data); + //@} + + /** + Clears all text. + */ + void Clear(); + + /** + Copies the data. + */ + void Copy(const wxRichTextHeaderFooterData& data); + + /** + Returns the font specified for printing the header and footer. + */ + const wxFont GetFont(); + + /** + Returns the margin between the text and the footer. + */ + int GetFooterMargin(); + + /** + Returns the footer text on odd or even pages, and at a given position on the + page (left, centre or right). + */ + wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Returns the margin between the text and the header. + */ + int GetHeaderMargin(); + + /** + Returns the header text on odd or even pages, and at a given position on the + page (left, centre or right). + */ + wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Returns @true if the header and footer will be shown on the first page. + */ + bool GetShowOnFirstPage(); + + /** + Helper function for getting the header or footer text, odd or even pages, and + at a given position on the page (left, centre or right). + */ + wxString GetText(int headerFooter, wxRichTextOddEvenPage page, + wxRichTextPageLocation location); + + /** + Returns the text colour for drawing the header and footer. + */ + const wxColour GetTextColour(); + + /** + Initialises the object. + */ + void Init(); + + /** + Sets the font for drawing the header and footer. + */ + void SetFont(const wxFont& font); + + /** + Sets the footer text on odd or even pages, and at a given position on the page + (left, centre or right). + */ + void SetFooterText(const wxString& text, + wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Sets the header text on odd or even pages, and at a given position on the page + (left, centre or right). + */ + void SetHeaderText(const wxString& text, + wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Sets the margins between text and header or footer, in tenths of a millimeter. + */ + void SetMargins(int headerMargin, int footerMargin); + + /** + Pass @true to show the header or footer on first page (the default). + */ + void SetShowOnFirstPage(bool showOnFirstPage); + + /** + Helper function for setting the header or footer text, odd or even pages, and + at a given position on the page (left, centre or right). + */ + void SetText(const wxString& text, int headerFooter, + wxRichTextOddEvenPage page, + wxRichTextPageLocation location); + + /** + Sets the text colour for drawing the header and footer. + */ + void SetTextColour(const wxColour& col); + + /** + Assignment operator. + */ + void operator operator=(const wxRichTextHeaderFooterData& data); +}; + + +/** + @class wxRichTextPrintout + @headerfile richtextprint.h wx/richtext/richtextprint.h + + This class implements print layout for wxRichTextBuffer. Instead of using it + directly, you + should normally use the wxRichTextPrinting class. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextPrintout : public wxPrintout +{ +public: + /** + ) + + Constructor. + */ + wxRichTextPrintout(); + + /** + Calculates scaling and text, header and footer rectangles. + */ + void CalculateScaling(wxDC* dc, wxRect& textRect, + wxRect& headerRect, + wxRect& footerRect); + + /** + Returns the header and footer data associated with the printout. + */ + const wxRichTextHeaderFooterData GetHeaderFooterData(); + + /** + Gets the page information. + */ + void GetPageInfo(int* minPage, int* maxPage, int* selPageFrom, + int* selPageTo); + + /** + Returns a pointer to the buffer being rendered. + */ + wxRichTextBuffer* GetRichTextBuffer(); + + /** + Returns @true if the given page exists in the printout. + */ + bool HasPage(int page); + + /** + Prepares for printing, laying out the buffer and calculating pagination. + */ + void OnPreparePrinting(); + + /** + Does the actual printing for this page. + */ + bool OnPrintPage(int page); + + /** + Sets the header and footer data associated with the printout. + */ + void SetHeaderFooterData(const wxRichTextHeaderFooterData& data); + + /** + Sets margins in 10ths of millimetre. Defaults to 1 inch for margins. + */ + void SetMargins(int top = 252, int bottom = 252, int left = 252, + int right = 252); + + /** + Sets the buffer to print. wxRichTextPrintout does not manage this pointer; it + should + be managed by the calling code, such as wxRichTextPrinting. + */ + void SetRichTextBuffer(wxRichTextBuffer* buffer); +}; + + +/** + @class wxRichTextPrinting + @headerfile richtextprint.h wx/richtext/richtextprint.h + + This class provides a simple interface for performing wxRichTextBuffer printing + and previewing. It uses wxRichTextPrintout for layout and rendering. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextPrinting : public wxObject +{ +public: + /** + , @b wxWindow*@e parentWindow = @NULL) + + Constructor. Optionally pass a title to be used in the preview frame and + printing wait dialog, and + also a parent window for these windows. + */ + wxRichTextPrinting(); + + /** + A convenience function to get the footer text. See wxRichTextHeaderFooterData + for details. + */ + wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Returns the internal wxRichTextHeaderFooterData object. + */ + const wxRichTextHeaderFooterData GetHeaderFooterData(); + + /** + A convenience function to get the header text. See wxRichTextHeaderFooterData + for details. + */ + wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Returns a pointer to the internal page setup data. + */ + wxPageSetupDialogData* GetPageSetupData(); + + /** + Returns the parent window to be used for the preview window and printing wait + dialog. + */ + wxWindow* GetParentWindow(); + + /** + Returns the dimensions to be used for the preview window. + */ + const wxRect GetPreviewRect(); + + /** + Returns a pointer to the internal print data. + */ + wxPrintData* GetPrintData(); + + /** + Returns the title of the preview window or printing wait caption. + */ + const wxString GetTitle(); + + /** + Shows the page setup dialog. + */ + void PageSetup(); + + /** + Shows a preview window for the given buffer. The function takes its own copy of + @e buffer. + */ + bool PreviewBuffer(const wxRichTextBuffer& buffer); + + /** + Shows a preview window for the given file. @e richTextFile can be a text file + or XML file, or other file + depending on the available file handlers. + */ + bool PreviewFile(const wxString& richTextFile); + + /** + Prints the given buffer. The function takes its own copy of @e buffer. + */ + bool PrintBuffer(const wxRichTextBuffer& buffer); + + /** + Prints the given file. @e richTextFile can be a text file or XML file, or other + file + depending on the available file handlers. + */ + bool PrintFile(const wxString& richTextFile); + + /** + A convenience function to set the footer text. See wxRichTextHeaderFooterData + for details. + */ + void SetFooterText(const wxString& text, + wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Sets the internal wxRichTextHeaderFooterData object. + */ + void SetHeaderFooterData(const wxRichTextHeaderFooterData& data); + + /** + Sets the wxRichTextHeaderFooterData font. + */ + void SetHeaderFooterFont(const wxFont& font); + + /** + Sets the wxRichTextHeaderFooterData text colour. + */ + void SetHeaderFooterTextColour(const wxColour& colour); + + /** + A convenience function to set the header text. See wxRichTextHeaderFooterData + for details. + */ + void SetHeaderText(const wxString& text, + wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Sets the page setup data. + */ + void SetPageSetupData(const wxPageSetupData& pageSetupData); + + /** + Sets the parent window to be used for the preview window and printing wait + dialog. + */ + void SetParentWindow(wxWindow* parent); + + /** + Sets the dimensions to be used for the preview window. + */ + void SetPreviewRect(const wxRect& rect); + + /** + Sets the print data. + */ + void SetPrintData(const wxPrintData& printData); + + /** + Pass @true to show the header and footer on the first page. + */ + void SetShowOnFirstPage(bool show); + + /** + Pass the title of the preview window or printing wait caption. + */ + void SetTitle(const wxString& title); +}; diff --git a/interface/richtext/richtextstyledlg.h b/interface/richtext/richtextstyledlg.h new file mode 100644 index 0000000000..a5ff5ab552 --- /dev/null +++ b/interface/richtext/richtextstyledlg.h @@ -0,0 +1,196 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextstyledlg.h +// Purpose: documentation for wxRichTextStyleOrganiserDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextStyleOrganiserDialog + @headerfile richtextstyledlg.h wx/richtext/richtextstyledlg.h + + This class shows a style sheet and allows the user to edit, add and remove + styles. + It can also be used as a style browser, for example if the application is not + using a permanent wxRichTextStyleComboCtrl or wxRichTextStyleListCtrl to + present styles. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextStyleOrganiserDialog : public wxDialog +{ +public: + //@{ + /** + Constructors. + + To create a dialog, pass a bitlist of @e flags (see below), a style sheet, a + text control to apply a selected style to (or @NULL), followed by the usual window parameters. + + To specify the operations available to the user, pass a combination of these + values to @e flags: + + + @b wxRICHTEXT_ORGANISER_DELETE_STYLES + + + Provides a button for deleting styles. + + @b wxRICHTEXT_ORGANISER_CREATE_STYLES + + + Provides buttons for creating styles. + + @b wxRICHTEXT_ORGANISER_APPLY_STYLES + + + Provides a button for applying the currently selected style to the selection. + + @b wxRICHTEXT_ORGANISER_EDIT_STYLES + + + Provides a button for editing styles. + + @b wxRICHTEXT_ORGANISER_RENAME_STYLES + + + Provides a button for renaming styles. + + @b wxRICHTEXT_ORGANISER_OK_CANCEL + + + Provides OK and Cancel buttons. + + @b wxRICHTEXT_ORGANISER_RENUMBER + + + Provides a checkbox for specifying that the selection should be renumbered. + + The following flags determine what will be displayed in the style list: + + + @b wxRICHTEXT_ORGANISER_SHOW_CHARACTER + + + Displays character styles only. + + @b wxRICHTEXT_ORGANISER_SHOW_PARAGRAPH + + + Displays paragraph styles only. + + @b wxRICHTEXT_ORGANISER_SHOW_LIST + + + Displays list styles only. + + @b wxRICHTEXT_ORGANISER_SHOW_ALL + + + Displays all styles. + + The following symbols define commonly-used combinations of flags: + + + @b wxRICHTEXT_ORGANISER_ORGANISE + + + Enable all style editing operations so the dialog behaves as a style organiser. + + @b wxRICHTEXT_ORGANISER_BROWSE + + + Show a list of all styles and their previews, but only allow application of a + style or + cancellation of the dialog. This makes the dialog behave as a style browser. + + @b wxRICHTEXT_ORGANISER_BROWSE_NUMBERING + + + Enables only list style browsing, plus a control to specify renumbering. This + allows the dialog to be used for applying list styles to the selection. + */ + wxRichTextStyleOrganiserDialog(int flags, + wxRichTextStyleSheet* sheet, + wxRichTextCtrl* ctrl, + wxWindow* parent, + wxWindowID id = wxID_ANY); + const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) + wxRichTextStyleOrganiserDialog(); + //@} + + /** + Applies the selected style to selection in the given control or the control + passed to the constructor. + */ + bool ApplyStyle(wxRichTextCtrl* ctrl = @NULL); + + /** + , @b const wxPoint&@e pos = wxDefaultPosition, @b const wxSize&@e size = + wxDefaultSize, @b long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) + + Creates the dialog. See + */ + bool Create(int flags, wxRichTextStyleSheet* sheet, + wxRichTextCtrl* ctrl, + wxWindow* parent, + wxWindowID id = wxID_ANY); + + /** + Returns @true if the user has opted to restart numbering. + */ + bool GetRestartNumbering(); + + /** + Returns the associated rich text control (if any). + */ + wxRichTextCtrl* GetRichTextCtrl(); + + /** + Returns selected style name. + */ + wxString GetSelectedStyle(); + + /** + Returns selected style definition. + */ + wxRichTextStyleDefinition* GetSelectedStyleDefinition(); + + /** + Returns the associated style sheet. + */ + wxRichTextStyleSheet* GetStyleSheet(); + + /** + Sets the flags used to control the interface presented to the user. + */ + void SetFlags(int flags); + + /** + Checks or unchecks the restart numbering checkbox. + */ + void SetRestartNumbering(bool restartNumbering); + + /** + Sets the control to be associated with the dialog, for the purposes of applying + a style to the selection. + */ + void SetRichTextCtrl(wxRichTextCtrl* ctrl); + + /** + Determines whether tooltips will be shown. + */ + void SetShowToolTips(bool show); + + /** + Sets the associated style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* sheet); + + /** + Returns the flags used to control the interface presented to the user. + */ + int GetFlags(); +}; diff --git a/interface/richtext/richtextstyles.h b/interface/richtext/richtextstyles.h new file mode 100644 index 0000000000..585c25836c --- /dev/null +++ b/interface/richtext/richtextstyles.h @@ -0,0 +1,673 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextstyles.h +// Purpose: documentation for wxRichTextStyleListCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextStyleListCtrl + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This class incorporates a wxRichTextStyleListBox and + a choice control that allows the user to select the category of style to view. + It is demonstrated in the wxRichTextCtrl sample in @c samples/richtext. + + To use wxRichTextStyleListCtrl, add the control to your window hierarchy and + call wxRichTextStyleListCtrl::SetStyleType with + one of wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, + wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, + wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and + wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST to set the current view. + Associate the control with a style sheet and rich text control with + SetStyleSheet and SetRichTextCtrl, + so that when a style is double-clicked, it is applied to the selection. + + @beginStyleTable + @style{wxRICHTEXTSTYLELIST_HIDE_TYPE_SELECTOR}: + This style hides the category selection control. + @endStyleTable + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextStyleListCtrl : public wxControl +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextStyleListCtrl(wxWindow* parent, + wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + wxRichTextStyleListCtrl(); + //@} + + /** + Creates the windows. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + + /** + Returns the associated rich text control, if any. + */ + wxRichTextCtrl* GetRichTextCtrl(); + + /** + Returns the wxChoice control used for selecting the style category. + */ + wxChoice* GetStyleChoice(); + + /** + Returns the wxListBox control used to view the style list. + */ + wxRichTextStyleListBox* GetStyleListBox(); + + /** + Returns the associated style sheet, if any. + */ + wxRichTextStyleSheet* GetStyleSheet(); + + /** + Returns the type of style to show in the list box. + */ + wxRichTextStyleListBox::wxRichTextStyleType GetStyleType(); + + /** + Associates the control with a wxRichTextCtrl. + */ + void SetRichTextCtrl(wxRichTextCtrl* ctrl); + + /** + Associates the control with a style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Sets the style type to display. One of + wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, + wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and + wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. + */ + void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType); + + /** + Updates the style list box. + */ + void UpdateStyles(); +}; + + +/** + @class wxRichTextStyleDefinition + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This is a base class for paragraph and character styles. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextStyleDefinition : public wxObject +{ +public: + /** + Constructor. + */ + wxRichTextStyleDefinition(const wxString& name = wxEmptyString); + + /** + Destructor. + */ + ~wxRichTextStyleDefinition(); + + /** + Returns the style on which this style is based. + */ + const wxString GetBaseStyle(); + + /** + Returns the style's description. + */ + const wxString GetDescription(); + + /** + Returns the style name. + */ + const wxString GetName(); + + //@{ + /** + Returns the attributes associated with this style. + */ + wxTextAttr GetStyle(); + const wxTextAttr GetStyle(); + //@} + + /** + Returns the style attributes combined with the attributes of the specified base + style, if any. This function works recursively. + */ + wxTextAttr GetStyleMergedWithBase(wxRichTextStyleSheet* sheet); + + /** + Sets the name of the style that this style is based on. + */ + void SetBaseStyle(const wxString& name); + + /** + Sets the style description. + */ + void SetDescription(const wxString& descr); + + /** + Sets the name of the style. + */ + void SetName(const wxString& name); + + /** + Sets the attributes for this style. + */ + void SetStyle(const wxTextAttr& style); +}; + + +/** + @class wxRichTextParagraphStyleDefinition + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This class represents a paragraph style definition, usually added to a + wxRichTextStyleSheet. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextParagraphStyleDefinition : public wxRichTextStyleDefinition +{ +public: + /** + Constructor. + */ + wxRichTextParagraphStyleDefinition(const wxString& name = wxEmptyString); + + /** + Destructor. + */ + ~wxRichTextParagraphStyleDefinition(); + + /** + Returns the style that should normally follow this style. + */ + const wxString GetNextStyle(); + + /** + Sets the style that should normally follow this style. + */ + void SetNextStyle(const wxString& name); +}; + + +/** + @class wxRichTextStyleListBox + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This is a listbox that can display the styles in a wxRichTextStyleSheet, + and apply the selection to an associated wxRichTextCtrl. + + See @c samples/richtext for an example of how to use it. + + @library{wxrichtext} + @category{FIXME} + + @seealso + wxRichTextStyleComboCtrl, @ref overview_wxrichtextctrloverview "wxRichTextCtrl + overview" +*/ +class wxRichTextStyleListBox : public wxHtmlListBox +{ +public: + /** + Constructor. + */ + wxRichTextStyleListBox(wxWindow* parent, + wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + + /** + Destructor. + */ + ~wxRichTextStyleListBox(); + + /** + Applies the @e ith style to the associated rich text control. + */ + void ApplyStyle(int i); + + /** + Converts units in tenths of a millimetre to device units. + */ + int ConvertTenthsMMToPixels(wxDC& dc, int units); + + /** + Creates a suitable HTML fragment for a definition. + */ + wxString CreateHTML(wxRichTextStyleDefinition* def); + + /** + If the return value is @true, clicking on a style name in the list will + immediately + apply the style to the associated rich text control. + */ + bool GetApplyOnSelection(); + + /** + Returns the wxRichTextCtrl associated with this listbox. + */ + wxRichTextCtrl* GetRichTextCtrl(); + + /** + Gets a style for a listbox index. + */ + wxRichTextStyleDefinition* GetStyle(size_t i); + + /** + Returns the style sheet associated with this listbox. + */ + wxRichTextStyleSheet* GetStyleSheet(); + + /** + Returns the type of style to show in the list box. + */ + wxRichTextStyleListBox::wxRichTextStyleType GetStyleType(); + + /** + Returns the HTML for this item. + */ + wxString OnGetItem(size_t n); + + /** + Implements left click behaviour, applying the clicked style to the + wxRichTextCtrl. + */ + void OnLeftDown(wxMouseEvent& event); + + /** + Reacts to selection. + */ + void OnSelect(wxCommandEvent& event); + + /** + If @e applyOnSelection is @true, clicking on a style name in the list will + immediately + apply the style to the associated rich text control. + */ + void SetApplyOnSelection(bool applyOnSelection); + + /** + Associates the listbox with a wxRichTextCtrl. + */ + void SetRichTextCtrl(wxRichTextCtrl* ctrl); + + /** + Associates the control with a style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Sets the style type to display. One of + wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, + wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and + wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. + */ + void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType); + + /** + Updates the list from the associated style sheet. + */ + void UpdateStyles(); +}; + + +/** + @class wxRichTextStyleComboCtrl + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This is a combo control that can display the styles in a wxRichTextStyleSheet, + and apply the selection to an associated wxRichTextCtrl. + + See @c samples/richtext for an example of how to use it. + + @library{wxrichtext} + @category{FIXME} + + @seealso + wxRichTextStyleListBox, @ref overview_wxrichtextctrloverview "wxRichTextCtrl + overview" +*/ +class wxRichTextStyleComboCtrl : public wxComboCtrl +{ +public: + /** + Constructor. + */ + wxRichTextStyleComboCtrl(wxWindow* parent, + wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + + /** + Destructor. + */ + ~wxRichTextStyleComboCtrl(); + + /** + Returns the wxRichTextCtrl associated with this control. + */ + wxRichTextCtrl* GetRichTextCtrl(); + + /** + Returns the style sheet associated with this control. + */ + wxRichTextStyleSheet* GetStyleSheet(); + + /** + Associates the control with a wxRichTextCtrl. + */ + void SetRichTextCtrl(wxRichTextCtrl* ctrl); + + /** + Associates the control with a style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Updates the combo control from the associated style sheet. + */ + void UpdateStyles(); +}; + + +/** + @class wxRichTextCharacterStyleDefinition + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This class represents a character style definition, usually added to a + wxRichTextStyleSheet. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextCharacterStyleDefinition : public wxRichTextStyleDefinition +{ +public: + /** + Constructor. + */ + wxRichTextCharacterStyleDefinition(const wxString& name = wxEmptyString); + + /** + Destructor. + */ + ~wxRichTextCharacterStyleDefinition(); +}; + + +/** + @class wxRichTextListStyleDefinition + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This class represents a list style definition, usually added to a + wxRichTextStyleSheet. + + The class inherits paragraph attributes from + wxRichTextStyleParagraphDefinition, and adds 10 further attribute objects, one for each level of a list. + When applying a list style to a paragraph, the list style's base and + appropriate level attributes are merged with the + paragraph's existing attributes. + + You can apply a list style to one or more paragraphs using + wxRichTextCtrl::SetListStyle. You + can also use the functions wxRichTextCtrl::NumberList, + wxRichTextCtrl::PromoteList and + wxRichTextCtrl::ClearListStyle. As usual, there are wxRichTextBuffer versions + of these functions + so that you can apply them directly to a buffer without requiring a control. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextListStyleDefinition : public wxRichTextParagraphStyleDefinition +{ +public: + /** + Constructor. + */ + wxRichTextListStyleDefinition(const wxString& name = wxEmptyString); + + /** + Destructor. + */ + ~wxRichTextListStyleDefinition(); + + /** + This function combines the given paragraph style with the list style's base + attributes and level style matching the given indent, returning the combined attributes. + If @e styleSheet is specified, the base style for this definition will also be + included in the result. + */ + wxTextAttr CombineWithParagraphStyle(int indent, + const wxTextAttr& paraStyle, + wxRichTextStyleSheet* styleSheet = @NULL); + + /** + This function finds the level (from 0 to 9) whose indentation attribute mostly + closely matches @e indent (expressed in tenths of a millimetre). + */ + int FindLevelForIndent(int indent); + + /** + This function combines the list style's base attributes and the level style + matching the given indent, returning the combined attributes. + If @e styleSheet is specified, the base style for this definition will also be + included in the result. + */ + wxTextAttr GetCombinedStyle(int indent, + wxRichTextStyleSheet* styleSheet = @NULL); + + /** + This function combines the list style's base attributes and the style for the + specified level, returning the combined attributes. + If @e styleSheet is specified, the base style for this definition will also be + included in the result. + */ + wxTextAttr GetCombinedStyleLevel(int level, + wxRichTextStyleSheet* styleSheet = @NULL); + + /** + Returns the style for the given level. @e level is a number between 0 and 9. + */ + const wxTextAttr* GetLevelAttributes(int level); + + /** + Returns the number of levels. This is hard-wired to 10. + + Returns the style for the given level. @e level is a number between 0 and 9. + */ + int GetLevelCount(); + + /** + Returns @true if the given level has numbered list attributes. + */ + int IsNumbered(int level); + + //@{ + /** + Sets the style for the given level. @e level is a number between 0 and 9. + + The first and most flexible form uses a wxTextAttr object, while the second + form is for convenient setting of the most commonly-used attributes. + */ + void SetLevelAttributes(int level, const wxTextAttr& attr); + void SetLevelAttributes(int level, int leftIndent, + int leftSubIndent, + int bulletStyle, + const wxString& bulletSymbol = wxEmptyString); + //@} +}; + + +/** + @class wxRichTextStyleSheet + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + A style sheet contains named paragraph and character styles that make it + easy for a user to apply combinations of attributes to a wxRichTextCtrl. + + You can use a wxRichTextStyleListBox in your + user interface to show available styles to the user, and allow application + of styles to the control. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextStyleSheet : public wxObject +{ +public: + /** + Constructor. + */ + wxRichTextStyleSheet(); + + /** + Destructor. + */ + ~wxRichTextStyleSheet(); + + /** + Adds a definition to the character style list. + */ + bool AddCharacterStyle(wxRichTextCharacterStyleDefinition* def); + + /** + Adds a definition to the list style list. + */ + bool AddListStyle(wxRichTextListStyleDefinition* def); + + /** + Adds a definition to the paragraph style list. + */ + bool AddParagraphStyle(wxRichTextParagraphStyleDefinition* def); + + /** + Adds a definition to the appropriate style list. + */ + bool AddStyle(wxRichTextStyleDefinition* def); + + /** + Deletes all styles. + */ + void DeleteStyles(); + + /** + Finds a character definition by name. + */ + wxRichTextCharacterStyleDefinition* FindCharacterStyle(const wxString& name); + + /** + Finds a list definition by name. + */ + wxRichTextListStyleDefinition* FindListStyle(const wxString& name); + + /** + Finds a paragraph definition by name. + */ + wxRichTextParagraphStyleDefinition* FindParagraphStyle(const wxString& name); + + /** + Finds a style definition by name. + */ + wxRichTextStyleDefinition* FindStyle(const wxString& name); + + /** + Returns the @e nth character style. + */ + wxRichTextCharacterStyleDefinition* GetCharacterStyle(size_t n); + + /** + Returns the number of character styles. + */ + size_t GetCharacterStyleCount(); + + /** + Returns the style sheet's description. + */ + const wxString GetDescription(); + + /** + Returns the @e nth list style. + */ + wxRichTextListStyleDefinition* GetListStyle(size_t n); + + /** + Returns the number of list styles. + */ + size_t GetListStyleCount(); + + /** + Returns the style sheet's name. + */ + const wxString GetName(); + + /** + Returns the @e nth paragraph style. + */ + wxRichTextParagraphStyleDefinition* GetParagraphStyle(size_t n); + + /** + Returns the number of paragraph styles. + */ + size_t GetParagraphStyleCount(); + + /** + Removes a character style. + */ + bool RemoveCharacterStyle(wxRichTextStyleDefinition* def, + bool deleteStyle = @false); + + /** + Removes a list style. + */ + bool RemoveListStyle(wxRichTextStyleDefinition* def, + bool deleteStyle = @false); + + /** + Removes a paragraph style. + */ + bool RemoveParagraphStyle(wxRichTextStyleDefinition* def, + bool deleteStyle = @false); + + /** + Removes a style. + */ + bool RemoveStyle(wxRichTextStyleDefinition* def, + bool deleteStyle = @false); + + /** + Sets the style sheet's description. + */ + void SetDescription(const wxString& descr); + + /** + Sets the style sheet's name. + */ + void SetName(const wxString& name); +}; diff --git a/interface/richtext/richtextsymboldlg.h b/interface/richtext/richtextsymboldlg.h new file mode 100644 index 0000000000..03a4a04e9f --- /dev/null +++ b/interface/richtext/richtextsymboldlg.h @@ -0,0 +1,198 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextsymboldlg.h +// Purpose: documentation for wxSymbolPickerDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSymbolPickerDialog + @headerfile richtextsymboldlg.h wx/richtext/richtextsymboldlg.h + + wxSymbolPickerDialog presents the user with a choice of fonts and a grid + of available characters. This modal dialog provides the application with + a selected symbol and optional font selection. + + Although this dialog is contained in the rich text library, the dialog + is generic and can be used in other contexts. + + To use the dialog, pass a default symbol specified as a string, an initial font + name, + and a current font name. The difference between the initial font and + current font is that the initial font determines what the font control will be + set to when the dialog shows - an empty string will show the selection @e + normal text. + The current font, on the other hand, is used by the dialog to determine what + font + to display the characters in, even when no initial font is selected. + This allows the user (and application) to distinguish between inserting a + symbol in the current font, and inserting it with a specified font. + + When the dialog is dismissed, the application can get the selected symbol + with GetSymbol and test whether a font was specified with UseNormalFont, + fetching the specified font with GetFontName. + + Here's a realistic example, inserting the supplied symbol into a + rich text control in either the current font or specified font. + + @code + wxRichTextCtrl* ctrl = (wxRichTextCtrl*) FindWindow(ID_RICHTEXT_CTRL); + + wxTextAttr attr; + attr.SetFlags(wxTEXT_ATTR_FONT); + ctrl-GetStyle(ctrl-GetInsertionPoint(), attr); + + wxString currentFontName; + if (attr.HasFont() && attr.GetFont().Ok()) + currentFontName = attr.GetFont().GetFaceName(); + + // Don't set the initial font in the dialog (so the user is choosing + // 'normal text', i.e. the current font) but do tell the dialog + // what 'normal text' is. + + wxSymbolPickerDialog dlg(wxT("*"), wxEmptyString, currentFontName, this); + + if (dlg.ShowModal() == wxID_OK) + { + if (dlg.HasSelection()) + { + long insertionPoint = ctrl-GetInsertionPoint(); + + ctrl-WriteText(dlg.GetSymbol()); + + if (!dlg.UseNormalFont()) + { + wxFont font(attr.GetFont()); + font.SetFaceName(dlg.GetFontName()); + attr.SetFont(font); + ctrl-SetStyle(insertionPoint, insertionPoint+1, attr); + } + } + } + @endcode + + @library{wxrichtext} + @category{cmndlg} +*/ +class wxSymbolPickerDialog : public wxDialog +{ +public: + //@{ + /** + Constructors. + + @param symbol + The initial symbol to show. Specify a single character in a string, or an empty + string. + + @param initialFont + The initial font to be displayed in the font list. If empty, the item normal + text will be selected. + + @param normalTextFont + The font the dialog will use to display the symbols if the initial font is + empty. + + @param parent + The dialog's parent. + + @param id + The dialog's identifier. + + @param title + The dialog's caption. + + @param pos + The dialog's position. + + @param size + The dialog's size. + + @param style + The dialog's window style. + */ + wxSymbolPickerDialog(const wxString& symbol, + const wxString& initialFont, + const wxString& normalTextFont, + wxWindow* parent, + wxWindowID id = wxID_ANY); + const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) + wxSymbolPickerDialog(); + //@} + + /** + , @b const wxPoint&@e pos = wxDefaultPosition, @b const wxSize&@e size = + wxDefaultSize, @b long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) + + Creation: see @ref wxsymbolpickerdialog() "the constructor" for details about + the parameters. + */ + bool Create(const wxString& symbol, const wxString& initialFont, + const wxString& normalTextFont, + wxWindow* parent, + wxWindowID id = wxID_ANY); + + /** + Returns the font name (the font reflected in the font list). + */ + wxString GetFontName(); + + /** + Returns @true if the dialog is showing the full range of Unicode characters. + */ + bool GetFromUnicode(); + + /** + Gets the font name used for displaying symbols in the absence of a selected + font. + */ + wxString GetNormalTextFontName(); + + /** + Gets the current or initial symbol as a string. + */ + wxString GetSymbol(); + + /** + Gets the selected symbol character as an integer. + */ + int GetSymbolChar(); + + /** + Returns @true if a symbol is selected. + */ + bool HasSelection(); + + /** + Sets the initial/selected font name. + */ + void SetFontName(const wxString& value); + + /** + Sets the internal flag indicating that the full Unicode range should be + displayed. + */ + void SetFromUnicode(bool value); + + /** + Sets the name of the font to be used in the absence of a selected font. + */ + void SetNormalTextFontName(const wxString& value); + + /** + Sets the symbol as a one or zero character string. + */ + void SetSymbol(const wxString& value); + + /** + Sets Unicode display mode. + */ + void SetUnicodeMode(bool unicodeMode); + + /** + Returns @true if the has specified normal text - that is, there is no selected + font. + */ + bool UseNormalFont(); +}; diff --git a/interface/richtext/richtextxml.h b/interface/richtext/richtextxml.h new file mode 100644 index 0000000000..ba322f93f4 --- /dev/null +++ b/interface/richtext/richtextxml.h @@ -0,0 +1,102 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextxml.h +// Purpose: documentation for wxRichTextXMLHandler class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextXMLHandler + @headerfile richtextxml.h wx/richtext/richtextxml.h + + A handler for loading and saving content in an XML format specific + to wxRichTextBuffer. You can either add the handler to the buffer + and load and save through the buffer or control API, or you can + create an instance of the handler on the stack and call its + functions directly. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextXMLHandler : public wxRichTextFileHandler +{ +public: + /** + , @b const wxString&@e ext = wxT("xml"), @b int@e type = wxRICHTEXT_TYPE_XML) + + Constructor. + */ + wxRichTextXMLHandler(); + + /** + Returns @true. + */ + bool CanLoad(); + + /** + Returns @true. + */ + bool CanSave(); + + /** + Creates XML code for a given character or paragraph style. + */ + wxString CreateStyle(const wxTextAttr& attr, bool isPara = @false); + + /** + Loads buffer context from the given stream. + */ + bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); + + /** + Saves buffer context to the given stream. + */ + bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); + + /** + Recursively exports an object to the stream. + */ + bool ExportXML(wxOutputStream& stream, wxMBConv* convMem, + wxMBConv* convFile, + wxRichTextObject& obj, + int level); + + /** + Helper function: gets node context. + */ + wxString GetNodeContent(wxXmlNode* node); + + /** + Helper function: gets a named parameter from the XML node. + */ + wxXmlNode* GetParamNode(wxXmlNode* node, const wxString& param); + + /** + Helper function: gets a named parameter from the XML node. + */ + wxString GetParamValue(wxXmlNode* node, const wxString& param); + + /** + Helper function: gets style parameters from the given XML node. + */ + bool GetStyle(wxTextAttr& attr, wxXmlNode* node, + bool isPara = @false); + + /** + Helper function: gets text from the node. + */ + wxString GetText(wxXmlNode* node, + const wxString& param = wxEmptyString, + bool translate = @false); + + /** + Helper function: returns @true if the node has the given parameter. + */ + bool HasParam(wxXmlNode* node, const wxString& param); + + /** + Recursively imports an object. + */ + bool ImportXML(wxRichTextBuffer* buffer, wxXmlNode* node); +}; diff --git a/interface/sashwin.h b/interface/sashwin.h new file mode 100644 index 0000000000..22e916b9d1 --- /dev/null +++ b/interface/sashwin.h @@ -0,0 +1,221 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sashwin.h +// Purpose: documentation for wxSashWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSashWindow + @wxheader{sashwin.h} + + wxSashWindow allows any of its edges to have a sash which can be dragged + to resize the window. The actual content window will be created by the + application + as a child of wxSashWindow. The window (or an ancestor) will be notified of a + drag + via a wxSashEvent notification. + + @beginStyleTable + @style{wxSW_3D}: + Draws a 3D effect sash and border. + @style{wxSW_3DSASH}: + Draws a 3D effect sash. + @style{wxSW_3DBORDER}: + Draws a 3D effect border. + @style{wxSW_BORDER}: + Draws a thin black border. + @endStyleTable + + @beginEventTable + @event{EVT_SASH_DRAGGED(id\, func)}: + Process a wxEVT_SASH_DRAGGED event, when the user has finished + dragging a sash. + @event{EVT_SASH_DRAGGED_RANGE(id1\, id2\, func)}: + Process a wxEVT_SASH_DRAGGED_RANGE event, when the user has + finished dragging a sash. The event handler is called when windows + with ids in the given range have their sashes dragged. + @endEventTable + + @library{wxadv} + @category{miscwnd} + + @seealso + wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview "Event + handling overview" +*/ +class wxSashWindow : public wxWindow +{ +public: + //@{ + /** + Constructs a sash window, which can be a child of a frame, dialog or any other + non-control window. + + @param parent + Pointer to a parent window. + + @param id + Window identifier. If -1, will automatically create an identifier. + + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxSashWindows + should generate a default position for the window. If using the wxSashWindow + class directly, supply + an actual position. + + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that wxSashWindows + should generate a default size for the window. + + @param style + Window style. For window styles, please see wxSashWindow. + + @param name + Window name. + */ + wxSashWindow(); + wxSashWindow(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLIP_CHILDREN | wxSW_3D, + const wxString& name = "sashWindow"); + //@} + + /** + Destructor. + */ + ~wxSashWindow(); + + /** + Gets the maximum window size in the x direction. + */ + int GetMaximumSizeX(); + + /** + Gets the maximum window size in the y direction. + */ + int GetMaximumSizeY(); + + /** + Gets the minimum window size in the x direction. + */ + int GetMinimumSizeX(); + + /** + Gets the minimum window size in the y direction. + */ + int GetMinimumSizeY(); + + /** + Returns @true if a sash is visible on the given edge, @false otherwise. + + @param edge + Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + + @sa SetSashVisible() + */ + bool GetSashVisible(wxSashEdgePosition edge); + + /** + Returns @true if the sash has a border, @false otherwise. + This function is obsolete since the sash border property is unused. + + @param edge + Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + + @sa SetSashBorder() + */ + bool HasBorder(wxSashEdgePosition edge); + + /** + Sets the maximum window size in the x direction. + */ + void SetMaximumSizeX(int min); + + /** + Sets the maximum window size in the y direction. + */ + void SetMaximumSizeY(int min); + + /** + Sets the minimum window size in the x direction. + */ + void SetMinimumSizeX(int min); + + /** + Sets the minimum window size in the y direction. + */ + void SetMinimumSizeY(int min); + + /** + Call this function to give the sash a border, or remove the border. + This function is obsolete since the sash border property is unused. + + @param edge + Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + + @param hasBorder + @true to give the sash a border visible, @false to remove it. + */ + void SetSashBorder(wxSashEdgePosition edge, bool hasBorder); + + /** + Call this function to make a sash visible or invisible on a particular edge. + + @param edge + Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + + @param visible + @true to make the sash visible, @false to make it invisible. + + @sa GetSashVisible() + */ + void SetSashVisible(wxSashEdgePosition edge, bool visible); +}; + + +/** + @class wxSashEvent + @wxheader{sashwin.h} + + A sash event is sent when the sash of a wxSashWindow has been + dragged by the user. + + @library{wxadv} + @category{FIXME} + + @seealso + wxSashWindow, @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxSashEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxSashEvent(int id = 0, wxSashEdgePosition edge = wxSASH_NONE); + + /** + Returns the rectangle representing the new size the window would be if the + resize was applied. It is + up to the application to set the window size if required. + */ + wxRect GetDragRect(); + + /** + Returns the status of the sash: one of wxSASH_STATUS_OK, + wxSASH_STATUS_OUT_OF_RANGE. + If the drag caused the notional bounding box of the window to flip over, for + example, the drag will be out of rage. + */ + wxSashDragStatus GetDragStatus(); + + /** + Returns the dragged edge. The return value is one of wxSASH_TOP, wxSASH_RIGHT, + wxSASH_BOTTOM, wxSASH_LEFT. + */ + wxSashEdgePosition GetEdge(); +}; diff --git a/interface/sckipc.h b/interface/sckipc.h new file mode 100644 index 0000000000..8319816fe7 --- /dev/null +++ b/interface/sckipc.h @@ -0,0 +1,307 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sckipc.h +// Purpose: documentation for wxTCPServer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTCPServer + @wxheader{sckipc.h} + + A wxTCPServer object represents the server part of a client-server conversation. + It emulates a DDE-style protocol, but uses TCP/IP which is available on most + platforms. + + A DDE-based implementation for Windows is available using wxDDEServer. + + @library{wxnet} + @category{FIXME} + + @seealso + wxTCPClient, wxTCPConnection, @ref overview_ipcoverview "IPC overview" +*/ +class wxTCPServer : public wxObject +{ +public: + /** + Constructs a server object. + */ + wxTCPServer(); + + /** + Registers the server using the given service name. Under Unix, the + string must contain an integer id which is used as an Internet port + number. @false is returned if the call failed (for example, the port + number is already in use). + */ + bool Create(const wxString& service); + + /** + When a client calls @b MakeConnection, the server receives the + message and this member is called. The application should derive a + member to intercept this message and return a connection object of + either the standard wxTCPConnection type, or of a user-derived type. If the + topic is "STDIO'', the application may wish to refuse the connection. + Under Unix, when a server is created the OnAcceptConnection message is + always sent for standard input and output. + */ + virtual wxConnectionBase * OnAcceptConnection(const wxString& topic); +}; + + +/** + @class wxTCPClient + @wxheader{sckipc.h} + + A wxTCPClient object represents the client part of a client-server conversation. + It emulates a DDE-style protocol, but uses TCP/IP which is available on most + platforms. + + A DDE-based implementation for Windows is available using wxDDEClient. + + To create a client which can communicate with a suitable server, + you need to derive a class from wxTCPConnection and another from wxTCPClient. + The custom wxTCPConnection class will intercept communications in + a 'conversation' with a server, and the custom wxTCPServer is required + so that a user-overridden wxTCPClient::OnMakeConnection member can return + a wxTCPConnection of the required class, when a connection is made. + + @library{wxnet} + @category{FIXME} + + @seealso + wxTCPServer, wxTCPConnection, @ref overview_ipcoverview "Interprocess + communications overview" +*/ +class wxTCPClient : public wxObject +{ +public: + /** + Constructs a client object. + */ + wxTCPClient(); + + /** + Tries to make a connection with a server specified by the host + (a machine name under Unix), service name (must + contain an integer port number under Unix), and a topic string. If the + server allows a connection, a wxTCPConnection object will be returned. + The type of wxTCPConnection returned can be altered by overriding + the OnMakeConnection() member to return your own + derived connection object. + */ + wxConnectionBase * MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); + + /** + The type of wxTCPConnection returned from a MakeConnection() call can + be altered by deriving the @b OnMakeConnection member to return your + own derived connection object. By default, a wxTCPConnection + object is returned. + + The advantage of deriving your own connection class is that it will + enable you to intercept messages initiated by the server, such + as wxTCPConnection::OnAdvise. You may also want to + store application-specific data in instances of the new class. + */ + wxConnectionBase * OnMakeConnection(); + + /** + Returns @true if this is a valid host name, @false otherwise. + */ + bool ValidHost(const wxString& host); +}; + + +/** + @class wxTCPConnection + @wxheader{sckipc.h} + + A wxTCPClient object represents the connection between a client and a server. + It emulates a DDE-style protocol, but uses TCP/IP which is available on most + platforms. + + A DDE-based implementation for Windows is available using wxDDEConnection. + + A wxTCPConnection object can be created by making a connection using a + wxTCPClient object, or by the acceptance of a connection by a + wxTCPServer object. The bulk of a conversation is controlled by + calling members in a @b wxTCPConnection object or by overriding its + members. + + An application should normally derive a new connection class from + wxTCPConnection, in order to override the communication event handlers + to do something interesting. + + @library{wxnet} + @category{FIXME} + + @seealso + wxTCPClient, wxTCPServer, @ref overview_ipcoverview "Interprocess + communications overview" +*/ +class wxTCPConnection : public wxObject +{ +public: + //@{ + /** + Constructs a connection object. If no user-defined connection object is + to be derived from wxTCPConnection, then the constructor should not be + called directly, since the default connection object will be provided on + requesting (or accepting) a connection. However, if the user defines his + or her own derived connection object, the wxTCPServer::OnAcceptConnection + and/or wxTCPClient::OnMakeConnection members should be replaced by + functions which construct the new connection object. If the arguments of + the wxTCPConnection constructor are void, then a default buffer is + associated with the connection. Otherwise, the programmer must provide a + a buffer and size of the buffer for the connection object to use in + transactions. + */ + wxTCPConnection(); + wxTCPConnection(void* buffer, size_t size); + //@} + + //@{ + /** + Called by the server application to advise the client of a change in + the data associated with the given item. Causes the client + connection's OnAdvise() + member to be called. Returns @true if successful. + */ + bool Advise(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Advise(const wxString& item, const char* data); + bool Advise(const wxString& item, const wchar_t* data); + bool Advise(const wxString& item, const wxString data); + //@} + + /** + Called by the client or server application to disconnect from the other + program; it causes the OnDisconnect() message + to be sent to the corresponding connection object in the other + program. The default behaviour of @b OnDisconnect is to delete the + connection, but the calling application must explicitly delete its + side of the connection having called @b Disconnect. Returns @true if + successful. + */ + bool Disconnect(); + + //@{ + /** + Called by the client application to execute a command on the server. Can + also be used to transfer arbitrary data to the server (similar + to Poke() in that respect). Causes the + server connection's OnExecute() member to be + called. Returns @true if successful. + */ + bool Execute(const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Execute(const char* data); + bool Execute(const wchar_t* data); + bool Execute(const wxString data); + //@} + + /** + Message sent to the client application when the server notifies it of a + change in the data associated with the given item. + */ + virtual bool OnAdvise(const wxString& topic, + const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the client or server application when the other + application notifies it to delete the connection. Default behaviour is + to delete the connection object. + */ + virtual bool OnDisconnect(); + + /** + Message sent to the server application when the client notifies it to + execute the given data. Note that there is no item associated with + this message. + */ + virtual bool OnExecute(const wxString& topic, const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the server application when the client notifies it to + accept the given data. + */ + virtual bool OnPoke(const wxString& topic, const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the server application when the client + calls Request(). The server + should respond by returning a character string from @b OnRequest, + or @NULL to indicate no data. + */ + virtual const void* OnRequest(const wxString& topic, + const wxString& item, + size_t * size, + wxIPCFormat format); + + /** + Message sent to the server application by the client, when the client + wishes to start an 'advise loop' for the given topic and item. The + server can refuse to participate by returning @false. + */ + virtual bool OnStartAdvise(const wxString& topic, + const wxString& item); + + /** + Message sent to the server application by the client, when the client + wishes to stop an 'advise loop' for the given topic and item. The + server can refuse to stop the advise loop by returning @false, although + this doesn't have much meaning in practice. + */ + virtual bool OnStopAdvise(const wxString& topic, + const wxString& item); + + //@{ + /** + Called by the client application to poke data into the server. Can be + used to transfer arbitrary data to the server. Causes the server + connection's OnPoke() member + to be called. Returns @true if successful. + */ + bool Poke(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Poke(const wxString& item, const char* data); + bool Poke(const wxString& item, const wchar_t* data); + bool Poke(const wxString& item, const wxString data); + //@} + + /** + Called by the client application to request data from the server. Causes + the server connection's OnRequest() member to be called. Returns a + character string (actually a pointer to the connection's buffer) if + successful, @NULL otherwise. + */ + const void* Request(const wxString& item, size_t * size, + wxIPCFormat format = wxIPC_TEXT); + + /** + Called by the client application to ask if an advise loop can be started + with the server. Causes the server connection's OnStartAdvise() + member to be called. Returns @true if the server okays it, @false + otherwise. + */ + bool StartAdvise(const wxString& item); + + /** + Called by the client application to ask if an advise loop can be + stopped. Causes the server connection's OnStopAdvise() member + to be called. Returns @true if the server okays it, @false otherwise. + */ + bool StopAdvise(const wxString& item); +}; diff --git a/interface/sckstrm.h b/interface/sckstrm.h new file mode 100644 index 0000000000..a104810a08 --- /dev/null +++ b/interface/sckstrm.h @@ -0,0 +1,56 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sckstrm.h +// Purpose: documentation for wxSocketOutputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSocketOutputStream + @wxheader{sckstrm.h} + + This class implements an output stream which writes data from + a connected socket. Note that this stream is purely sequential + and it does not support seeking. + + @library{wxnet} + @category{streams} + + @seealso + wxSocketBase +*/ +class wxSocketOutputStream : public wxOutputStream +{ +public: + /** + Creates a new write-only socket stream using the specified initialized + socket connection. + */ + wxSocketOutputStream(wxSocketBase& s); +}; + + +/** + @class wxSocketInputStream + @wxheader{sckstrm.h} + + This class implements an input stream which reads data from + a connected socket. Note that this stream is purely sequential + and it does not support seeking. + + @library{wxnet} + @category{streams} + + @seealso + wxSocketBase +*/ +class wxSocketInputStream : public wxInputStream +{ +public: + /** + Creates a new read-only socket stream using the specified initialized + socket connection. + */ + wxSocketInputStream(wxSocketBase& s); +}; diff --git a/interface/scopeguard.h b/interface/scopeguard.h new file mode 100644 index 0000000000..aa86b0876f --- /dev/null +++ b/interface/scopeguard.h @@ -0,0 +1,42 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: scopeguard.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + //@{ +/** + This family of macros is similar to wxON_BLOCK_EXIT + but calls a method of the given object instead of a free function. +*/ + wxON_BLOCK_EXIT_OBJ0(obj, method); + wxON_BLOCK_EXIT_OBJ1(obj, method, p1); + wxON_BLOCK_EXIT_OBJ2(obj, method, p1, p2); +//@} + + + //@{ +/** + This family of macros allows to ensure that the global function @e func + with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is + executed on scope exit, whether due to a normal function return or because an + exception has been thrown. A typical example of its usage: + + @code + void *buf = malloc(size); + wxON_BLOCK_EXIT1(free, buf); + @endcode + + Please see the original article by Andrei Alexandrescu and Petru Marginean + published in December 2000 issue of C/C++ Users Journal for more + details. + + @sa wxON_BLOCK_EXIT_OBJ +*/ + wxON_BLOCK_EXIT0(func); + wxON_BLOCK_EXIT1(func, p1); + wxON_BLOCK_EXIT2(func, p1, p2); +//@} + diff --git a/interface/scrolbar.h b/interface/scrolbar.h new file mode 100644 index 0000000000..c4c8d624b2 --- /dev/null +++ b/interface/scrolbar.h @@ -0,0 +1,157 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: scrolbar.h +// Purpose: documentation for wxScrollBar class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxScrollBar + @wxheader{scrolbar.h} + + A wxScrollBar is a control that represents a horizontal or + vertical scrollbar. It is distinct from the two scrollbars that some windows + provide automatically, but the two types of scrollbar share the way + events are received. + + @beginStyleTable + @style{wxSB_HORIZONTAL}: + Specifies a horizontal scrollbar. + @style{wxSB_VERTICAL}: + Specifies a vertical scrollbar. + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{scrollbar.png} + + @seealso + @ref overview_scrollingoverview "Scrolling overview", @ref + overview_eventhandlingoverview "Event handling overview", wxScrolledWindow +*/ +class wxScrollBar : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a scrollbar. + + @param parent + Parent window. Must be non-@NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. If wxDefaultPosition is specified then a default position + is chosen. + + @param size + Window size. If wxDefaultSize is specified then a default size is + chosen. + + @param style + Window style. See wxScrollBar. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxScrollBar(); + wxScrollBar(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSB_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "scrollBar"); + //@} + + /** + Destructor, destroying the scrollbar. + */ + ~wxScrollBar(); + + /** + Scrollbar creation function called by the scrollbar constructor. + See wxScrollBar() for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSB_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "scrollBar"); + + /** + Returns the page size of the scrollbar. This is the number of scroll units + that will be scrolled when the user pages up or down. Often it is the + same as the thumb size. + + @sa SetScrollbar() + */ + int GetPageSize(); + + /** + Returns the length of the scrollbar. + + @sa SetScrollbar() + */ + int GetRange(); + + /** + Returns the current position of the scrollbar thumb. + + @sa SetThumbPosition() + */ + int GetThumbPosition(); + + /** + Returns the thumb or 'view' size. + + @sa SetScrollbar() + */ + int GetThumbSize(); + + /** + Sets the scrollbar properties. + + @param position + The position of the scrollbar in scroll units. + + @param thumbSize + The size of the thumb, or visible portion of the scrollbar, in scroll units. + + @param range + The maximum position of the scrollbar. + + @param pageSize + The size of the page size in scroll units. This is the number of units + the scrollbar will scroll when it is paged up or down. Often it is the same as + the thumb size. + + @param refresh + @true to redraw the scrollbar, @false otherwise. + + @remarks Let's say you wish to display 50 lines of text, using the same + font. The window is sized so that you can only see 16 + lines at a time. + */ + virtual void SetScrollbar(int position, int thumbSize, int range, + int pageSize, + bool refresh = @true); + + /** + Sets the position of the scrollbar. + + @param viewStart + The position of the scrollbar thumb. + + @sa GetThumbPosition() + */ + void SetThumbPosition(int viewStart); +}; diff --git a/interface/scrolwin.h b/interface/scrolwin.h new file mode 100644 index 0000000000..5f6196ef7d --- /dev/null +++ b/interface/scrolwin.h @@ -0,0 +1,366 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: scrolwin.h +// Purpose: documentation for wxScrolledWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxScrolledWindow + @wxheader{scrolwin.h} + + The wxScrolledWindow class manages scrolling for its client area, transforming + the coordinates according to the scrollbar positions, and setting the + scroll positions, thumb sizes and ranges according to the area in view. + + Starting from version 2.4 of wxWidgets, there are several ways to use a + wxScrolledWindow. In particular, there are now three ways to set the + size of the scrolling area: + + One way is to set the scrollbars directly using a call to + wxScrolledWindow::SetScrollbars. + This is the way it used to be in any previous version of wxWidgets + and it will be kept for backwards compatibility. + + An additional method of manual control, which requires a little less + computation of your own, is to set the total size of the scrolling area by + calling either wxWindow::SetVirtualSize, + or wxWindow::FitInside, and setting the + scrolling increments for it by calling + wxScrolledWindow::SetScrollRate. + Scrolling in some orientation is enabled by setting a non-zero increment + for it. + + The most automatic and newest way is to simply let sizers determine the + scrolling area. This is now the default when you set an interior sizer + into a wxScrolledWindow with wxWindow::SetSizer. + The scrolling area will be set to the size requested by the sizer and + the scrollbars will be assigned for each orientation according to the need + for them and the scrolling increment set by + wxScrolledWindow::SetScrollRate. + As above, scrolling is only enabled in orientations with a non-zero + increment. You can influence the minimum size of the scrolled area + controlled by a sizer by calling + wxWindow::SetVirtualSizeHints. + (calling wxScrolledWindow::SetScrollbars + has analogous effects in wxWidgets 2.4 -- in later versions it may not continue + to override the sizer) + + Note: if Maximum size hints are still supported by SetVirtualSizeHints, use + them at your own dire risk. They may or may not have been removed for 2.4, + but it really only makes sense to set minimum size hints here. We should + probably replace SetVirtualSizeHints with SetMinVirtualSize or similar + and remove it entirely in future. + + As with all windows, an application can draw onto a wxScrolledWindow using + a @ref overview_dcoverview "device context". + + You have the option of handling the OnPaint handler + or overriding the wxScrolledWindow::OnDraw function, which is + passed a pre-scrolled device context (prepared by + wxScrolledWindow::DoPrepareDC). + + If you don't wish to calculate your own scrolling, you must call DoPrepareDC + when not drawing from + within OnDraw, to set the device origin for the device context according to the + current + scroll position. + + A wxScrolledWindow will normally scroll itself and therefore its child windows + as well. It + might however be desired to scroll a different window than itself: e.g. when + designing a + spreadsheet, you will normally only have to scroll the (usually white) cell + area, whereas the + (usually grey) label area will scroll very differently. For this special + purpose, you can + call wxScrolledWindow::SetTargetWindow which means that pressing + the scrollbars will scroll a different window. + + Note that the underlying system knows nothing about scrolling coordinates, so + that all system + functions (mouse events, expose events, refresh calls etc) as well as the + position of subwindows + are relative to the "physical" origin of the scrolled window. If the user + insert a child window at + position (10,10) and scrolls the window down 100 pixels (moving the child + window out of the visible + area), the child window will report a position of (10,-90). + + @beginStyleTable + @style{wxRETAINED}: + Uses a backing pixmap to speed refreshes. Motif only. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @seealso + wxScrollBar, wxClientDC, wxPaintDC, wxVScrolledWindow +*/ +class wxScrolledWindow : public wxPanel +{ +public: + //@{ + /** + Constructor. + + @param parent + Parent window. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. If a position of (-1, -1) is specified then a default position + is chosen. + + @param size + Window size. If a size of (-1, -1) is specified then the window is sized + appropriately. + + @param style + Window style. See wxScrolledWindow. + + @param name + Window name. + + @remarks The window is initially created without visible scrollbars. Call + SetScrollbars() to specify how big + the virtual window size should be. + */ + wxScrolledWindow(); + wxScrolledWindow(wxWindow* parent, wxWindowID id = -1, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxHSCROLL | wxVSCROLL, + const wxString& name = "scrolledWindow"); + //@} + + /** + Destructor. + */ + ~wxScrolledWindow(); + + /** + Translates the logical coordinates to the device ones. For example, if a window + is + scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, + 0) + (as always), but the logical coordinates are (0, 10) and so the call to + CalcScrolledPosition(0, 10, xx, yy) will return 0 in yy. + + @sa CalcUnscrolledPosition() + */ + void CalcScrolledPosition(int x, int y, int * xx, int * yy); + + /** + Translates the device coordinates to the logical ones. For example, if a window + is + scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, + 0) + (as always), but the logical coordinates are (0, 10) and so the call to + CalcUnscrolledPosition(0, 0, xx, yy) will return 10 in yy. + + @sa CalcScrolledPosition() + */ + void CalcUnscrolledPosition(int x, int y, int * xx, int * yy); + + /** + Creates the window for two-step construction. Derived classes + should call or replace this function. See wxScrolledWindow() + for details. + */ + bool Create(wxWindow* parent, wxWindowID id = -1, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxHSCROLL | wxVSCROLL, + const wxString& name = "scrolledWindow"); + + /** + Call this function to prepare the device context for drawing a scrolled image. + It + sets the device origin according to the current scroll position. + + DoPrepareDC is called automatically within the default OnPaint() event + handler, so your OnDraw() override + will be passed a 'pre-scrolled' device context. However, if you wish to draw + from + outside of OnDraw (via OnPaint), or you wish to implement OnPaint yourself, you + must + call this function yourself. For example: + */ + void DoPrepareDC(wxDC& dc); + + /** + Enable or disable physical scrolling in the given direction. Physical + scrolling is the physical transfer of bits up or down the + screen when a scroll event occurs. If the application scrolls by a + variable amount (e.g. if there are different font sizes) then physical + scrolling will not work, and you should switch it off. Note that you + will have to reposition child windows yourself, if physical scrolling + is disabled. + + @param xScrolling + If @true, enables physical scrolling in the x direction. + + @param yScrolling + If @true, enables physical scrolling in the y direction. + + @remarks Physical scrolling may not be available on all platforms. Where + it is available, it is enabled by default. + */ + void EnableScrolling(bool xScrolling, bool yScrolling); + + /** + Get the number of pixels per scroll unit (line), in each direction, as set + by SetScrollbars(). A value of zero indicates no + scrolling in that direction. + + @param xUnit + Receives the number of pixels per horizontal unit. + + @param yUnit + Receives the number of pixels per vertical unit. + + @sa SetScrollbars(), GetVirtualSize() + */ + void GetScrollPixelsPerUnit(int* xUnit, int* yUnit); + + /** + Get the position at which the visible portion of the window starts. + + @param x + Receives the first visible x position in scroll units. + + @param y + Receives the first visible y position in scroll units. + + @remarks If either of the scrollbars is not at the home position, x + and/or y will be greater than zero. Combined with + wxWindow::GetClientSize, the application can use this + function to efficiently redraw only the visible + portion of the window. The positions are in logical + scroll units, not pixels, so to convert to pixels you + will have to multiply by the number of pixels per + scroll increment. + + @sa SetScrollbars() + */ + void GetViewStart(int* x, int* y); + + /** + Gets the size in device units of the scrollable window area (as + opposed to the client size, which is the area of the window currently + visible). + + @param x + Receives the length of the scrollable window, in pixels. + + @param y + Receives the height of the scrollable window, in pixels. + + @remarks Use wxDC::DeviceToLogicalX and wxDC::DeviceToLogicalY to + translate these units to logical units. + + @sa SetScrollbars(), GetScrollPixelsPerUnit() + */ + void GetVirtualSize(int* x, int* y); + + /** + Motif only: @true if the window has a backing bitmap. + */ + bool IsRetained(); + + /** + Called by the default paint event handler to allow the application to define + painting behaviour without having to worry about calling + DoPrepareDC(). + + Instead of overriding this function you may also just process the paint event + in the derived class as usual, but then you will have to call DoPrepareDC() + yourself. + */ + virtual void OnDraw(wxDC& dc); + + /** + This function is for backwards compatibility only and simply calls + DoPrepareDC() now. Notice that it is + not called by the default paint event handle (DoPrepareDC() is), so + overriding this method in your derived class is useless. + */ + void PrepareDC(wxDC& dc); + + /** + Scrolls a window so the view start is at the given point. + + @param x + The x position to scroll to, in scroll units. + + @param y + The y position to scroll to, in scroll units. + + @remarks The positions are in scroll units, not pixels, so to convert to + pixels you will have to multiply by the number of + pixels per scroll increment. If either parameter is + -1, that position will be ignored (no change in that + direction). + + @sa SetScrollbars(), GetScrollPixelsPerUnit() + */ + void Scroll(int x, int y); + + /** + Set the horizontal and vertical scrolling increment only. See the pixelsPerUnit + parameter in SetScrollbars. + */ + void SetScrollRate(int xstep, int ystep); + + /** + Sets up vertical and/or horizontal scrollbars. + + @param pixelsPerUnitX + Pixels per scroll unit in the horizontal direction. + + @param pixelsPerUnitY + Pixels per scroll unit in the vertical direction. + + @param noUnitsX + Number of units in the horizontal direction. + + @param noUnitsY + Number of units in the vertical direction. + + @param xPos + Position to initialize the scrollbars in the horizontal direction, in scroll + units. + + @param yPos + Position to initialize the scrollbars in the vertical direction, in scroll + units. + + @param noRefresh + Will not refresh window if @true. + + @remarks The first pair of parameters give the number of pixels per + 'scroll step', i.e. amount moved when the up or down + scroll arrows are pressed. The second pair gives the + length of scrollbar in scroll steps, which sets the + size of the virtual window. + + @sa wxWindow::SetVirtualSize + */ + void SetScrollbars(int pixelsPerUnitX, int pixelsPerUnitY, + int noUnitsX, + int noUnitsY, + int xPos = 0, + int yPos = 0, + bool noRefresh = @false); + + /** + Call this function to tell wxScrolledWindow to perform the actual scrolling on + a different window (and not on itself). + */ + void SetTargetWindow(wxWindow* window); +}; diff --git a/interface/settings.h b/interface/settings.h new file mode 100644 index 0000000000..d6d6c4df0d --- /dev/null +++ b/interface/settings.h @@ -0,0 +1,493 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: settings.h +// Purpose: documentation for wxSystemSettings class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSystemSettings + @wxheader{settings.h} + + wxSystemSettings allows the application to ask for details about + the system. This can include settings such as standard colours, fonts, + and user interface element sizes. + + @library{wxcore} + @category{misc} + + @seealso + wxFont, wxColour +*/ +class wxSystemSettings : public wxObject +{ +public: + /** + Default constructor. You don't need to create an instance of wxSystemSettings + since all of its functions are static. + */ + wxSystemSettings(); + + /** + Returns a system colour. + + @e index can be one of: + + + @b wxSYS_COLOUR_SCROLLBAR + + + The scrollbar grey area. + + @b wxSYS_COLOUR_BACKGROUND + + + The desktop colour. + + @b wxSYS_COLOUR_ACTIVECAPTION + + + Active window caption. + + @b wxSYS_COLOUR_INACTIVECAPTION + + + Inactive window caption. + + @b wxSYS_COLOUR_MENU + + + Menu background. + + @b wxSYS_COLOUR_WINDOW + + + Window background. + + @b wxSYS_COLOUR_WINDOWFRAME + + + Window frame. + + @b wxSYS_COLOUR_MENUTEXT + + + Menu text. + + @b wxSYS_COLOUR_WINDOWTEXT + + + Text in windows. + + @b wxSYS_COLOUR_CAPTIONTEXT + + + Text in caption, size box and scrollbar arrow box. + + @b wxSYS_COLOUR_ACTIVEBORDER + + + Active window border. + + @b wxSYS_COLOUR_INACTIVEBORDER + + + Inactive window border. + + @b wxSYS_COLOUR_APPWORKSPACE + + + Background colour MDI applications. + + @b wxSYS_COLOUR_HIGHLIGHT + + + Item(s) selected in a control. + + @b wxSYS_COLOUR_HIGHLIGHTTEXT + + + Text of item(s) selected in a control. + + @b wxSYS_COLOUR_BTNFACE + + + Face shading on push buttons. + + @b wxSYS_COLOUR_BTNSHADOW + + + Edge shading on push buttons. + + @b wxSYS_COLOUR_GRAYTEXT + + + Greyed (disabled) text. + + @b wxSYS_COLOUR_BTNTEXT + + + Text on push buttons. + + @b wxSYS_COLOUR_INACTIVECAPTIONTEXT + + + Colour of text in active captions. + + @b wxSYS_COLOUR_BTNHIGHLIGHT + + + Highlight colour for buttons (same as wxSYS_COLOUR_3DHILIGHT). + + @b wxSYS_COLOUR_3DDKSHADOW + + + Dark shadow for three-dimensional display elements. + + @b wxSYS_COLOUR_3DLIGHT + + + Light colour for three-dimensional display elements. + + @b wxSYS_COLOUR_INFOTEXT + + + Text colour for tooltip controls. + + @b wxSYS_COLOUR_INFOBK + + + Background colour for tooltip controls. + + @b wxSYS_COLOUR_DESKTOP + + + Same as wxSYS_COLOUR_BACKGROUND. + + @b wxSYS_COLOUR_3DFACE + + + Same as wxSYS_COLOUR_BTNFACE. + + @b wxSYS_COLOUR_3DSHADOW + + + Same as wxSYS_COLOUR_BTNSHADOW. + + @b wxSYS_COLOUR_3DHIGHLIGHT + + + Same as wxSYS_COLOUR_BTNHIGHLIGHT. + + @b wxSYS_COLOUR_3DHILIGHT + + + Same as wxSYS_COLOUR_BTNHIGHLIGHT. + + @b wxSYS_COLOUR_BTNHILIGHT + + + Same as wxSYS_COLOUR_BTNHIGHLIGHT. + */ + static wxColour GetColour(wxSystemColour index); + + /** + Returns a system font. + + @e index can be one of: + + + @b wxSYS_OEM_FIXED_FONT + + + Original equipment manufacturer dependent fixed-pitch font. + + @b wxSYS_ANSI_FIXED_FONT + + + Windows fixed-pitch font. + + @b wxSYS_ANSI_VAR_FONT + + + Windows variable-pitch (proportional) font. + + @b wxSYS_SYSTEM_FONT + + + System font. + + @b wxSYS_DEVICE_DEFAULT_FONT + + + Device-dependent font (Windows NT only). + + @b wxSYS_DEFAULT_GUI_FONT + + + Default font for user interface + objects such as menus and dialog boxes. Note that with modern GUIs nothing + guarantees that the same font is used for all GUI elements, so some controls + might use a different font by default. + */ + static wxFont GetFont(wxSystemFont index); + + /** + Returns the value of a system metric, or -1 if the metric is not supported on + the current system. + The value of @e win determines if the metric returned is a global value or + a wxWindow based value, in which case it might determine the widget, the + display the window is on, or something similar. The window given should be as + close to the + metric as possible (e.g a wxTopLevelWindow in case of the wxSYS_CAPTION_Y + metric). + + @e index can be one of: + + + @b wxSYS_MOUSE_BUTTONS + + + Number of buttons on mouse, or zero if no mouse was installed. + + @b wxSYS_BORDER_X + + + Width of single border. + + @b wxSYS_BORDER_Y + + + Height of single border. + + @b wxSYS_CURSOR_X + + + Width of cursor. + + @b wxSYS_CURSOR_Y + + + Height of cursor. + + @b wxSYS_DCLICK_X + + + Width in pixels of rectangle within which two successive mouse + clicks must fall to generate a double-click. + + @b wxSYS_DCLICK_Y + + + Height in pixels of rectangle within which two successive mouse + clicks must fall to generate a double-click. + + @b wxSYS_DCLICK_MSEC + + + Maximal time, in milliseconds, which may + pass between subsequent clicks for a double click to be generated. + + @b wxSYS_DRAG_X + + + Width in pixels of a rectangle centered on a drag point + to allow for limited movement of the mouse pointer before a drag operation + begins. + + @b wxSYS_DRAG_Y + + + Height in pixels of a rectangle centered on a drag point + to allow for limited movement of the mouse pointer before a drag operation + begins. + + @b wxSYS_EDGE_X + + + Width of a 3D border, in pixels. + + @b wxSYS_EDGE_Y + + + Height of a 3D border, in pixels. + + @b wxSYS_HSCROLL_ARROW_X + + + Width of arrow bitmap on horizontal scrollbar. + + @b wxSYS_HSCROLL_ARROW_Y + + + Height of arrow bitmap on horizontal scrollbar. + + @b wxSYS_HTHUMB_X + + + Width of horizontal scrollbar thumb. + + @b wxSYS_ICON_X + + + The default width of an icon. + + @b wxSYS_ICON_Y + + + The default height of an icon. + + @b wxSYS_ICONSPACING_X + + + Width of a grid cell for items in large icon view, + in pixels. Each item fits into a rectangle of this size when arranged. + + @b wxSYS_ICONSPACING_Y + + + Height of a grid cell for items in large icon view, + in pixels. Each item fits into a rectangle of this size when arranged. + + @b wxSYS_WINDOWMIN_X + + + Minimum width of a window. + + @b wxSYS_WINDOWMIN_Y + + + Minimum height of a window. + + @b wxSYS_SCREEN_X + + + Width of the screen in pixels. + + @b wxSYS_SCREEN_Y + + + Height of the screen in pixels. + + @b wxSYS_FRAMESIZE_X + + + Width of the window frame for a wxTHICK_FRAME window. + + @b wxSYS_FRAMESIZE_Y + + + Height of the window frame for a wxTHICK_FRAME window. + + @b wxSYS_SMALLICON_X + + + Recommended width of a small icon (in window captions, and small icon view). + + @b wxSYS_SMALLICON_Y + + + Recommended height of a small icon (in window captions, and small icon view). + + @b wxSYS_HSCROLL_Y + + + Height of horizontal scrollbar in pixels. + + @b wxSYS_VSCROLL_X + + + Width of vertical scrollbar in pixels. + + @b wxSYS_VSCROLL_ARROW_X + + + Width of arrow bitmap on a vertical scrollbar. + + @b wxSYS_VSCROLL_ARROW_Y + + + Height of arrow bitmap on a vertical scrollbar. + + @b wxSYS_VTHUMB_Y + + + Height of vertical scrollbar thumb. + + @b wxSYS_CAPTION_Y + + + Height of normal caption area. + + @b wxSYS_MENU_Y + + + Height of single-line menu bar. + + @b wxSYS_NETWORK_PRESENT + + + 1 if there is a network present, 0 otherwise. + + @b wxSYS_PENWINDOWS_PRESENT + + + 1 if PenWindows is installed, 0 otherwise. + + @b wxSYS_SHOW_SOUNDS + + + Non-zero if the user requires an application to present information visually in + situations + where it would otherwise present the information only in audible form; zero + otherwise. + + @b wxSYS_SWAP_BUTTONS + + + Non-zero if the meanings of the left and right mouse buttons are swapped; zero + otherwise. + + @e win is a pointer to the window for which the metric is requested. + Specifying the @e win parameter is encouraged, because some metrics on some + ports are not supported without one, + or they might be capable of reporting better values if given one. If a window + does not make sense for a metric, + one should still be given, as for example it might determine which displays + cursor width is requested with + wxSYS_CURSOR_X. + */ + static int GetMetric(wxSystemMetric index, wxWindow* win = @NULL); + + /** + Returns the screen type. The return value is one of: + + + @b wxSYS_SCREEN_NONE + + + Undefined screen type + + @b wxSYS_SCREEN_TINY + + + Tiny screen, less than 320x240 + + @b wxSYS_SCREEN_PDA + + + PDA screen, 320x240 or more but less than 640x480 + + @b wxSYS_SCREEN_SMALL + + + Small screen, 640x480 or more but less than 800x600 + + @b wxSYS_SCREEN_DESKTOP + + + Desktop screen, 800x600 or more + */ + static wxSystemScreenType GetScreenType(); +}; diff --git a/interface/sizer.h b/interface/sizer.h new file mode 100644 index 0000000000..35af97b40f --- /dev/null +++ b/interface/sizer.h @@ -0,0 +1,1395 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sizer.h +// Purpose: documentation for wxStdDialogButtonSizer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStdDialogButtonSizer + @wxheader{sizer.h} + + This class creates button layouts which conform to the standard button spacing + and ordering defined by the platform + or toolkit's user interface guidelines (if such things exist). By using this + class, you can ensure that all your + standard dialogs look correct on all major platforms. Currently it conforms to + the Windows, GTK+ and Mac OS X + human interface guidelines. + + When there aren't interface guidelines defined for a particular platform or + toolkit, wxStdDialogButtonSizer reverts + to the Windows implementation. + + To use this class, first add buttons to the sizer by calling AddButton (or + SetAffirmativeButton, SetNegativeButton, + or SetCancelButton) and then call Realize in order to create the actual button + layout used. Other than these special + operations, this sizer works like any other sizer. + + If you add a button with wxID_SAVE, on Mac OS X the button will be renamed to + "Save" and + the wxID_NO button will be renamed to "Don't Save" in accordance with the Mac + OS X Human Interface Guidelines. + + @library{wxcore} + @category{FIXME} + + @seealso + wxSizer, @ref overview_sizeroverview "Sizer overview", + wxDialog::CreateButtonSizer +*/ +class wxStdDialogButtonSizer : public wxBoxSizer +{ +public: + /** + Constructor for a wxStdDialogButtonSizer. + */ + wxStdDialogButtonSizer(); + + /** + Adds a button to the wxStdDialogButtonSizer. The button must have one of the + following identifiers: + + wxID_OK + wxID_YES + wxID_SAVE + wxID_APPLY + wxID_CLOSE + wxID_NO + wxID_CANCEL + wxID_HELP + wxID_CONTEXT_HELP + */ + void AddButton(wxButton* button); + + /** + Rearranges the buttons and applies proper spacing between buttons to make them + match the platform or toolkit's interface guidelines. + */ + void Realize(); + + /** + Sets the affirmative button for the sizer. This allows you to use identifiers + other than the standard identifiers outlined above. + */ + void SetAffirmativeButton(wxButton* button); + + /** + Sets the cancel button for the sizer. This allows you to use identifiers other + than the standard identifiers outlined above. + */ + void SetCancelButton(wxButton* button); + + /** + Sets the negative button for the sizer. This allows you to use identifiers + other than the standard identifiers outlined above. + */ + void SetNegativeButton(wxButton* button); +}; + + +/** + @class wxSizerItem + @wxheader{sizer.h} + + The wxSizerItem class is used to track the position, size and other + attributes of each item managed by a wxSizer. It is not + usually necessary to use this class because the sizer elements can also be + identified by their positions or window or sizer pointers but sometimes it may + be more convenient to use it directly. + + @library{wxcore} + @category{FIXME} +*/ +class wxSizerItem : public wxObject +{ +public: + //@{ + /** + Construct a sizer item for tracking a subsizer. + */ + wxSizerItem(int width, int height, int proportion, int flag, + int border, wxObject* userData); + wxSizerItem(wxWindow* window, const wxSizerFlags& flags); + wxSizerItem(wxWindow* window, int proportion, int flag, + int border, + wxObject* userData); + wxSizerItem(wxSizer* window, const wxSizerFlags& flags); + wxSizerItem(wxSizer* sizer, int proportion, int flag, + int border, + wxObject* userData); + //@} + + /** + Deletes the user data and subsizer, if any. + */ + ~wxSizerItem(); + + /** + Calculates the minimum desired size for the item, including any space + needed by borders. + */ + wxSize CalcMin(); + + /** + Destroy the window or the windows in a subsizer, depending on the type + of item. + */ + void DeleteWindows(); + + /** + Enable deleting the SizerItem without destroying the contained sizer. + */ + void DetachSizer(); + + /** + Return the border attribute. + */ + int GetBorder(); + + /** + Return the flags attribute. + */ + int GetFlag(); + + /** + Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has + not been set. + */ + int GetId(); + + /** + Get the minimum size needed for the item. + */ + wxSize GetMinSize(); + + /** + What is the current position of the item, as set in the last Layout. + */ + wxPoint GetPosition(); + + /** + Get the proportion item attribute. + */ + int GetProportion(); + + /** + Get the ration item attribute. + */ + float GetRatio(); + + /** + Get the rectangle of the item on the parent window, excluding borders. + */ + wxRect GetRect(); + + /** + Get the current size of the item, as set in the last Layout. + */ + wxSize GetSize(); + + /** + If this item is tracking a sizer, return it. @NULL otherwise. + */ + wxSizer* GetSizer(); + + /** + If this item is tracking a spacer, return its size. + */ + const wxSize GetSpacer(); + + /** + Get the userData item attribute. + */ + wxObject* GetUserData(); + + /** + If this item is tracking a window then return it. @NULL otherwise. + */ + wxWindow* GetWindow(); + + /** + Returns @true if this item is a window or a spacer and it is shown or if this + item is a sizer and not all its elements are hidden. In other words, for sizer + items, all of the child elements must be hidden for the sizer itself to be + considered hidden. + */ + bool IsShown(); + + /** + Is this item a sizer? + */ + bool IsSizer(); + + /** + Is this item a spacer? + */ + bool IsSpacer(); + + /** + Is this item a window? + */ + bool IsWindow(); + + /** + Set the border item attribute. + */ + void SetBorder(int border); + + /** + Set the position and size of the space allocated to the sizer, and + adjust the position and size of the item to be within that space + taking alignment and borders into account. + */ + void SetDimension(const wxPoint& pos, const wxSize& size); + + /** + Set the flag item attribute. + */ + void SetFlag(int flag); + + /** + Sets the numeric id of the wxSizerItem to @e id. + */ + void SetId(int id); + + /** + + */ + void SetInitSize(int x, int y); + + /** + Set the proportion item attribute. + */ + void SetProportion(int proportion); + + //@{ + /** + Set the ratio item attribute. + */ + void SetRatio(int width, int height); + void SetRatio(wxSize size); + void SetRatio(float ratio); + //@} + + /** + Set the sizer tracked by this item. + */ + void SetSizer(wxSizer* sizer); + + /** + Set the size of the spacer tracked by this item. + */ + void SetSpacer(const wxSize& size); + + /** + Set the window to be tracked by thsi item. + */ + void SetWindow(wxWindow* window); + + /** + Set the show item attribute, which sizers use to determine if the item + is to be made part of the layout or not. If the item is tracking a + window then it is shown or hidden as needed. + */ + void Show(bool show); +}; + + +/** + @class wxSizerFlags + @wxheader{sizer.h} + + Normally, when you add an item to a sizer via + wxSizer::Add, you have to specify a lot of flags and + parameters which can be unwieldy. This is where wxSizerFlags comes in: it + allows you to specify all parameters using the named methods instead. For + example, instead of + + @code + sizer-Add(ctrl, 0, wxEXPAND | wxALL, 10); + @endcode + + you can now write + + @code + sizer-Add(ctrl, wxSizerFlags().Expand().Border(10)); + @endcode + + This is more readable and also allows you to create wxSizerFlags objects which + can be reused for several sizer items. + + @code + wxSizerFlags flagsExpand(1); + flagsExpand.Expand().Border(10); + + sizer-Add(ctrl1, flagsExpand); + sizer-Add(ctrl2, flagsExpand); + @endcode + + Note that by specification, all methods of wxSizerFlags return the wxSizerFlags + object itself to allowing chaining multiple methods calls like in the examples + above. + + @library{wxcore} + @category{FIXME} + + @seealso + wxSizer +*/ +class wxSizerFlags +{ +public: + /** + Creates the wxSizer with the proportion specified by @e proportion. + */ + wxSizerFlags(int proportion = 0); + + /** + Sets the alignment of this wxSizerFlags to @e align. + + Note that if this method is not called, the wxSizerFlags has no specified + alignment. + + @sa Top(), Left(), Right(), + Bottom(), Centre() + */ + wxSizerFlags Align(int align = 0); + + //@{ + /** + Sets the wxSizerFlags to have a border of a number of pixels specified by + @e borderinpixels with the directions specified by @e direction. + + In the overloaded version without @e borderinpixels parameter, the border of + default size, as returned by GetDefaultBorder(), + is used. + */ + wxSizerFlags Border(int direction, int borderinpixels); + wxSizerFlags Border(int direction = wxALL); + //@} + + /** + Aligns the object to the bottom, shortcut for @c Align(wxALIGN_BOTTOM) + + @sa Align() + */ + wxSizerFlags Bottom(); + + /** + Sets the object of the wxSizerFlags to center itself in the area it is given. + */ + wxSizerFlags Center(); + + /** + Center() for people with the other dialect of english. + */ + wxSizerFlags Centre(); + + /** + Sets the border in the given @e direction having twice the default border + size. + */ + wxSizerFlags DoubleBorder(int direction = wxALL); + + /** + Sets the border in left and right directions having twice the default border + size. + */ + wxSizerFlags DoubleHorzBorder(); + + /** + Sets the object of the wxSizerFlags to expand to fill as much area as it can. + */ + wxSizerFlags Expand(); + + /** + Set the @c wxFIXED_MINSIZE flag which indicates that the initial size of + the window should be also set as its minimal size. + */ + wxSizerFlags FixedMinSize(); + + /** + Returns the border used by default in Border() method. + */ + static int GetDefaultBorder(); + + /** + Aligns the object to the left, shortcut for @c Align(wxALIGN_LEFT) + + @sa Align() + */ + wxSizerFlags Left(); + + /** + Sets the proportion of this wxSizerFlags to @e proportion + */ + wxSizerFlags Proportion(int proportion = 0); + + /** + Aligns the object to the right, shortcut for @c Align(wxALIGN_RIGHT) + + @sa Align() + */ + wxSizerFlags Right(); + + /** + Set the @c wx_SHAPED flag which indicates that the elements should + always keep the fixed width to height ratio equal to its original value. + */ + wxSizerFlags Shaped(); + + /** + Aligns the object to the top, shortcut for @c Align(wxALIGN_TOP) + + @sa Align() + */ +#define wxSizerFlags Top() /* implementation is private */ + + /** + Sets the border in the given @e direction having thrice the default border + size. + */ + wxSizerFlags TripleBorder(int direction = wxALL); +}; + + +/** + @class wxNotebookSizer + @wxheader{sizer.h} + + @b This class is deprecated and should not be used in new code! It is no + longer needed, wxNotebook control can be inserted + into any sizer class and its minimal size will be determined correctly. + See @ref overview_sizeroverview "wxSizer overview" for more information. + + wxNotebookSizer is a specialized sizer to make sizers work in connection + with using notebooks. This sizer is different from any other sizer as + you must not add any children to it - instead, it queries the notebook class + itself. + The only thing this sizer does is to determine the size of the biggest + page of the notebook and report an adjusted minimal size to a more toplevel + sizer. + + @library{wxbase} + @category{FIXME} + + @seealso + wxSizer, wxNotebook, @ref overview_sizeroverview "Sizer overview" +*/ +class wxNotebookSizer : public wxSizer +{ +public: + /** + Constructor. It takes an associated notebook as its only parameter. + */ + wxNotebookSizer(wxNotebook* notebook); + + /** + Returns the notebook associated with the sizer. + */ + wxNotebook* GetNotebook(); +}; + + +/** + @class wxFlexGridSizer + @wxheader{sizer.h} + + A flex grid sizer is a sizer which lays out its children in a two-dimensional + table with all table fields in one row having the same + height and all fields in one column having the same width, but all + rows or all columns are not necessarily the same height or width as in + the wxGridSizer. + + Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one + direction but unequally ("flexibly") in the other. If the sizer is only + flexible in one direction (this can be changed using + wxFlexGridSizer::SetFlexibleDirection), + it needs to be decided how the sizer should grow in the other ("non-flexible") + direction in order to fill the available space. The + wxFlexGridSizer::SetNonFlexibleGrowMode method + serves this purpose. + + @library{wxcore} + @category{winlayout} + + @seealso + wxSizer, @ref overview_sizeroverview "Sizer overview" +*/ +class wxFlexGridSizer : public wxGridSizer +{ +public: + //@{ + /** + Constructor for a wxGridSizer. @e rows and @e 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. @e vgap and @e hgap define extra space between + all children. + */ + wxFlexGridSizer(int rows, int cols, int vgap, int hgap); + wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0); + //@} + + /** + Specifies that column @e idx (starting from zero) should be grown if + there is extra space available to the sizer. + + The @e proportion parameter has the same meaning as the stretch factor for + the sizers except that if all proportions are 0, + then all columns are resized equally (instead of not being resized at all). + */ + void AddGrowableCol(size_t idx, int proportion = 0); + + /** + Specifies that row idx (starting from zero) should be grown if there + is extra space available to the sizer. + + See AddGrowableCol() for the description + of @e proportion parameter. + */ + void AddGrowableRow(size_t idx, int proportion = 0); + + /** + Returns a wxOrientation value that specifies whether the sizer flexibly + resizes its columns, rows, or both (default). + + @returns One of the following values: + + @sa SetFlexibleDirection() + */ + int GetFlexibleDirection(); + + /** + Returns the value that specifies how the sizer grows in the "non-flexible" + direction if there is one. + + @returns One of the following values: + + @sa SetFlexibleDirection(), + SetNonFlexibleGrowMode() + */ + int GetNonFlexibleGrowMode(); + + /** + Specifies that column idx is no longer growable. + */ + void RemoveGrowableCol(size_t idx); + + /** + Specifies that row idx is no longer growable. + */ + void RemoveGrowableRow(size_t idx); + + /** + Specifies whether the sizer should flexibly resize its columns, rows, or + both. Argument @c direction can be @c wxVERTICAL, @c wxHORIZONTAL + or @c wxBOTH (which is the default value). Any other value is ignored. See + @ref getflexibledrection() GetFlexibleDirection for the + explanation of these values. + + Note that this method does not trigger relayout. + */ + void SetFlexibleDirection(int direction); + + /** + Specifies how the sizer should grow in the non-flexible direction if + there is one (so + SetFlexibleDirection() must have + been called previously). Argument @e mode can be one of those documented in + GetNonFlexibleGrowMode(), please + see there for their explanation. + + Note that this method does not trigger relayout. + */ + void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode); +}; + + +/** + @class wxSizer + @wxheader{sizer.h} + + wxSizer is the abstract base class used for laying out subwindows in a window. + You + cannot use wxSizer directly; instead, you will have to use one of the sizer + classes derived from it. Currently there are wxBoxSizer, + wxStaticBoxSizer, + wxGridSizer, + wxFlexGridSizer, + wxWrapSizer + and wxGridBagSizer. + + The layout algorithm used by sizers in wxWidgets is closely related to layout + in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. + It is + based upon the idea of the individual subwindows reporting their minimal + required + size and their ability to get stretched if the size of the parent window has + changed. + This will most often mean that the programmer does not set the original size of + a dialog in the beginning, rather the dialog will be assigned a sizer and this + sizer + will be queried about the recommended size. The sizer in turn will query its + children, which can be normal windows, empty space or other sizers, so that + a hierarchy of sizers can be constructed. Note that wxSizer does not derive + from wxWindow + and thus does not interfere with tab ordering and requires very little + resources compared + to a real window on screen. + + What makes sizers so well fitted for use in wxWidgets is the fact that every + control + reports its own minimal size and the algorithm can handle differences in font + sizes + or different window (dialog item) sizes on different platforms without + problems. If e.g. + the standard font as well as the overall design of Motif widgets requires more + space than + on Windows, the initial dialog size will automatically be bigger on Motif than + on Windows. + + Sizers may also be used to control the layout of custom drawn items on the + window. The + Add, Insert, and Prepend functions return a pointer to the newly added + wxSizerItem. Just + add empty space of the desired size and attributes, and then use the + wxSizerItem::GetRect + method to determine where the drawing operations should take place. + + Please notice that sizers, like child windows, are owned by the library and + will be deleted by it which implies that they must be allocated on the heap. + However if you create a sizer and do not add it to another sizer or window, the + library wouldn't be able to delete such an orphan sizer and in this, and only + this, case it should be deleted explicitly. + + @b wxPython note: If you wish to create a sizer class in wxPython you should + derive the class from @c wxPySizer in order to get Python-aware + capabilities for the various virtual methods. + + @library{wxcore} + @category{winlayout} + + @seealso + @ref overview_sizeroverview "Sizer overview" +*/ +class wxSizer : public wxObject +{ +public: + /** + The constructor. Note that wxSizer is an abstract base class and may not + be instantiated. + */ + wxSizer(); + + /** + The destructor. + */ + ~wxSizer(); + + //@{ + /** + Appends a child to the sizer. wxSizer itself is an abstract class, but the + parameters are + equivalent in the derived classes that you will instantiate to use it so they + are described + here: + + @param window + The window to be added to the sizer. Its initial size (either set explicitly by + the + user or calculated internally when using wxDefaultSize) is interpreted as the + minimal and in many + cases also the initial size. + + @param sizer + The (child-)sizer to be added to the sizer. This allows placing a child sizer + in a + sizer and thus to create hierarchies of sizers (typically a vertical box as the + top sizer and several + horizontal boxes on the level beneath). + + @param width and height + The dimension of a spacer to be added to the sizer. Adding spacers to sizers + gives more flexibility in the design of dialogs; imagine for example a + horizontal box with two buttons at the + bottom of a dialog: you might want to insert a space between the two buttons + and make that space stretchable + using the proportion flag and the result will be that the left button will be + aligned with the left + side of the dialog and the right button with the right side - the space in + between will shrink and grow with + the dialog. + + @param proportion + Although the meaning of this parameter is undefined in wxSizer, it is used in + wxBoxSizer + to indicate if a child of a sizer can change its size in the main orientation + of the wxBoxSizer - where + 0 stands for not changeable and a value of more than zero is interpreted + relative to the value of other + children of the same wxBoxSizer. For example, you might have a horizontal + wxBoxSizer with three children, two + of which are supposed to change their size with the sizer. Then the two + stretchable windows would get a + value of 1 each to make them grow and shrink equally with the sizer's + horizontal dimension. + + @param flag + This parameter can be used to set a number of flags + which can be combined using the binary OR operator |. Two main + behaviours are defined using these flags. One is the border around a + window: the border parameter determines the border width whereas + the flags given here determine which side(s) of the item that the + border will be added. The other flags determine how the sizer item + behaves when the space allotted to the sizer changes, and is somewhat + dependent on the specific kind of sizer used. + + wxTOP + + wxBOTTOM + + wxLEFT + + wxRIGHT + + wxALL + + + These flags are used to specify which side(s) of + the sizer item the border width will apply to. + + + wxEXPAND + + + The item will be expanded to fill + the space assigned to the item. + + wxSHAPED + + + The item will be expanded as much + as possible while also maintaining its aspect ratio + + wxFIXED_MINSIZE + + + Normally wxSizers will use + GetAdjustedBestSize to + determine what the minimal size of window items should be, and will + use that size to calculate the layout. This allows layouts to + adjust when an item changes and its best size becomes + different. If you would rather have a window item stay the size it + started with then use wxFIXED_MINSIZE. + + wxALIGN_CENTER wxALIGN_CENTRE + + wxALIGN_LEFT + + wxALIGN_RIGHT + + wxALIGN_TOP + + wxALIGN_BOTTOM + + wxALIGN_CENTER_VERTICAL wxALIGN_CENTRE_VERTICAL + + wxALIGN_CENTER_HORIZONTAL wxALIGN_CENTRE_HORIZONTAL + + + The wxALIGN flags allow you to + specify the alignment of the item within the space allotted to it by + the sizer, adjusted for the border if any. + + @param border + Determines the border width, if the flag + parameter is set to include any border flag. + + @param userData + Allows an extra object to be attached to the sizer + item, for use in derived classes when sizing information is more + complex than the proportion and flag will allow for. + + @param flags + A wxSizerFlags object that + enables you to specify most of the above parameters more conveniently. + */ + wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags); + wxSizerItem* Add(wxWindow* window, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags); + wxSizerItem* Add(wxSizer* sizer, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Add(int width, int height, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + //@} + + /** + Adds non-stretchable space to the sizer. More readable way of calling + wxSizer::Add(size, size, 0). + */ + wxSizerItem* AddSpacer(int size); + + /** + Adds stretchable space to the sizer. More readable way of calling + wxSizer::Add(0, 0, prop). + */ + wxSizerItem* AddStretchSpacer(int prop = 1); + + /** + This method is abstract and has to be overwritten by any derived class. + Here, the sizer will do the actual calculation of its children's minimal sizes. + */ + wxSize CalcMin(); + + /** + Detaches all children from the sizer. If @e delete_windows is @true then + child windows will also be deleted. + */ + void Clear(bool delete_windows = @false); + + /** + Computes client area size for @e window so that it matches the + sizer's minimal size. Unlike GetMinSize(), this + method accounts for other constraints imposed on @e window, namely display's + size (returned size will never be too large for the display) and maximum + window size if previously set by + wxWindow::SetMaxSize. + + The returned value is suitable for passing to + wxWindow::SetClientSize or + wxWindow::SetMinClientSize. + + @sa ComputeFittingWindowSize(), Fit() + */ + wxSize ComputeFittingClientSize(wxWindow* window); + + /** + Like ComputeFittingClientSize(), + but converts the result into window size. + + The returned value is suitable for passing to + wxWindow::SetSize or + wxWindow::SetMinSize. + + @sa ComputeFittingClientSize(), Fit() + */ + wxSize ComputeFittingWindowSize(wxWindow* window); + + //@{ + /** + Detach a child from the sizer without destroying it. @e window is the window to + be + detached, @e sizer is the equivalent sizer and @e index is the position of + the child in the sizer, typically 0 for the first item. This method does not + cause any layout or resizing to take place, call Layout() + to update the layout "on screen" after detaching a child from the sizer. + + Returns @true if the child item was found and detached, @false otherwise. + + @sa Remove() + */ + bool Detach(wxWindow* window); + bool Detach(wxSizer* sizer); + bool Detach(size_t index); + //@} + + /** + Tell the sizer to resize the @e window so that its client area matches the + sizer's minimal size + (ComputeFittingClientSize() is called + to determine it). + This is commonly done in the constructor of the window + itself, see sample in the description + of wxBoxSizer. Returns the new window size. + + @sa ComputeFittingClientSize(), ComputeFittingWindowSize() + */ +#define wxSize Fit(wxWindow* window) /* implementation is private */ + + /** + Tell the sizer to resize the virtual size of the @e window to match the sizer's + minimal size. This will not alter the on screen size of the window, but may + cause + the addition/removal/alteration of scrollbars required to view the virtual area + in + windows which manage it. + + @sa wxScrolledWindow::SetScrollbars, SetVirtualSizeHints() + */ + void FitInside(wxWindow* window); + + //@{ + /** + Returns the list of the items in this sizer. The elements of type-safe + wxList @c wxSizerItemList are objects of type + @ref overview_wxsizeritem "wxSizerItem *". + */ + const wxSizerItemList GetChildren(); + wxSizerItemList GetChildren(); + //@} + + /** + Returns the window this sizer is used in or @NULL if none. + */ + wxWindow * GetContainingWindow(); + + //@{ + /** + Finds item of the sizer which holds given @e window, @e sizer or is located + in sizer at position @e index. + Use parameter @e recursive to search in subsizers too. + + Returns pointer to item or @NULL. + */ + wxSizerItem * GetItem(wxWindow* window, bool recursive = @false); + wxSizerItem * GetItem(wxSizer* sizer, bool recursive = @false); + wxSizerItem * GetItem(size_t index); + //@} + + /** + Finds item of the sizer which has the given @e id. This @e id is not the + window id but the id of the wxSizerItem itself. This is mainly useful for + retrieving the sizers created from XRC resources. + + Use parameter @e recursive to search in subsizers too. + + Returns pointer to item or @NULL. + */ + wxSizerItem * GetItemById(int id, bool recursive = @false); + + /** + Returns the minimal size of the sizer. This is either the combined minimal + size of all the children and their borders or the minimal size set by + SetMinSize(), depending on which is bigger. + + Note that the returned value is client size, not window size. + In particular, if you use the value to set toplevel window's minimal or + actual size, use wxWindow::SetMinClientSize + or wxWindow::SetClientSize, not + wxWindow::SetMinSize + or wxWindow::SetSize. + */ + wxSize GetMinSize(); + + /** + Returns the current position of the sizer. + */ + wxPoint GetPosition(); + + /** + Returns the current size of the sizer. + */ + wxSize GetSize(); + + //@{ + /** + Hides the @e window, @e sizer, or item at @e index. + To make a sizer item disappear, use Hide() followed by Layout(). + Use parameter @e recursive to hide elements found in subsizers. + + Returns @true if the child item was found, @false otherwise. + + @sa IsShown(), Show() + */ + bool Hide(wxWindow* window, bool recursive = @false); + bool Hide(wxSizer* sizer, bool recursive = @false); + bool Hide(size_t index); + //@} + + //@{ + /** + Insert a child into the sizer before any existing item at + See Add() for the meaning of the other parameters. + + @param index. + + index + The position this child should assume in the sizer. + */ + wxSizerItem* Insert(size_t index, wxWindow* window, + const wxSizerFlags& flags); + wxSizerItem* Insert(size_t index, wxWindow* window, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Insert(size_t index, wxSizer* sizer, + const wxSizerFlags& flags); + wxSizerItem* Insert(size_t index, wxSizer* sizer, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Insert(size_t index, int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + //@} + + /** + Inserts non-stretchable space to the sizer. More readable way of calling + wxSizer::Insert(size, size, 0). + */ + wxSizerItem* InsertSpacer(size_t index, int size); + + /** + Inserts stretchable space to the sizer. More readable way of calling + wxSizer::Insert(0, 0, prop). + */ + wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); + + //@{ + /** + Returns @true if the @e window, @e sizer, or item at @e index is shown. + + @sa Hide(), Show() + */ + bool IsShown(wxWindow* window); + bool IsShown(wxSizer* sizer); + bool IsShown(size_t index); + //@} + + /** + Call this to force layout of the children anew, e.g. after having added a child + to or removed a child (window, other sizer or space) from the sizer while + keeping + the current dimension. + */ + void Layout(); + + //@{ + /** + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. + */ + wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags); + wxSizerItem* Prepend(wxWindow* window, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Prepend(wxSizer* sizer, + const wxSizerFlags& flags); + wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = @NULL); + wxSizerItem* Prepend(int width, int height, + int proportion = 0, + int flag = 0, + int border= 0, + wxObject* userData = @NULL); + //@} + + /** + Prepends non-stretchable space to the sizer. More readable way of calling + wxSizer::Prepend(size, size, 0). + */ + wxSizerItem* PrependSpacer(int size); + + /** + Prepends stretchable space to the sizer. More readable way of calling + wxSizer::Prepend(0, 0, prop). + */ + wxSizerItem* PrependStretchSpacer(int prop = 1); + + /** + This method is abstract and has to be overwritten by any derived class. + Here, the sizer will do the actual calculation of its children's positions + and sizes. + */ + void RecalcSizes(); + + //@{ + /** + Removes a child from the sizer and destroys it if it is a sizer or a spacer, + but not if it is a window (because windows are owned by their parent window, + not the sizer). @e sizer is the wxSizer to be removed, + @e index is the position of the child in the sizer, e.g. 0 for the first item. + This method does not cause any layout or resizing to take place, call + Layout() to update the layout "on screen" after removing a + child from the sizer. + + @b NB: The method taking a wxWindow* parameter is deprecated as it does not + destroy the window as would usually be expected from Remove. You should use + Detach() in new code instead. There is + currently no wxSizer method that will both detach and destroy a wxWindow item. + + Returns @true if the child item was found and removed, @false otherwise. + */ + bool Remove(wxWindow* window); + bool Remove(wxSizer* sizer); + bool Remove(size_t index); + //@} + + //@{ + /** + Detaches the given @e oldwin, @e oldsz child from the sizer and + replaces it with the given window, sizer, or wxSizerItem. + + The detached child is removed @b only if it is a sizer or a spacer + (because windows are owned by their parent window, not the sizer). + + Use parameter @e recursive to search the given element recursively in subsizers. + This method does not cause any layout or resizing to take place, call + Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. + */ + bool Replace(wxWindow* oldwin, wxWindow* newwin, + bool recursive = @false); + bool Replace(wxSizer* oldsz, wxSizer* newsz, + bool recursive = @false); + bool Remove(size_t oldindex, wxSizerItem* newitem); + //@} + + /** + Call this to force the sizer to take the given dimension and thus force the + items owned + by the sizer to resize themselves according to the rules defined by the + parameter in the + Add() and Prepend() methods. + */ + void SetDimension(int x, int y, int width, int height); + + //@{ + /** + Set an item's minimum size by window, sizer, or position. The item will be + found recursively + in the sizer's descendants. This function enables an application to set the + size of an item + after initial creation. + */ + void SetItemMinSize(wxWindow* window, int width, int height); + void SetItemMinSize(wxSizer* sizer, int width, int height); + void SetItemMinSize(size_t index, int width, int height); + //@} + + //@{ + /** + Call this to give the sizer a minimal size. Normally, the sizer will calculate + its + minimal size based purely on how much space its children need. After calling + this + method GetMinSize() will return either the minimal size + as requested by its children or the minimal size set here, depending on which is + bigger. + */ + void SetMinSize(int width, int height); + void SetMinSize(const wxSize& size); + //@} + + /** + This method first calls Fit() and then + wxTopLevelWindow::SetSizeHints on the @e window + passed to it. This only makes sense when @e window is actually a + wxTopLevelWindow such as a wxFrame or a + wxDialog, since SetSizeHints only has any effect in these classes. + It does nothing in normal windows or controls. + + This method is implicitly used by wxWindow::SetSizerAndFit + which is commonly invoked in the constructor of a toplevel window itself (see + the sample in the description of wxBoxSizer) if the + toplevel window is resizable. + */ + void SetSizeHints(wxWindow* window); + + /** + Tell the sizer to set the minimal size of the @e window virtual area to match + the sizer's + minimal size. For windows with managed scrollbars this will set them + appropriately. + + @sa wxScrolledWindow::SetScrollbars + */ + void SetVirtualSizeHints(wxWindow* window); + + //@{ + /** + Shows or hides the @e window, @e sizer, or item at @e index. + To make a sizer item disappear or reappear, use Show() followed by Layout(). + Use parameter @e recursive to show or hide elements found in subsizers. + + Returns @true if the child item was found, @false otherwise. + + @sa Hide(), IsShown() + */ + bool Show(wxWindow* window, bool show = @true, + bool recursive = @false); + bool Show(wxSizer* sizer, bool show = @true, + bool recursive = @false); + bool Show(size_t index, bool show = @true); + //@} +}; + + +/** + @class wxGridSizer + @wxheader{sizer.h} + + A grid sizer is a sizer which lays out its children in a two-dimensional + table with all table fields having the same size, + i.e. the width of each field is the width of the widest child, + the height of each field is the height of the tallest child. + + @library{wxcore} + @category{winlayout} + + @seealso + wxSizer, @ref overview_sizeroverview "Sizer overview" +*/ +class wxGridSizer : public wxSizer +{ +public: + //@{ + /** + Constructor for a wxGridSizer. @e rows and @e 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. @e vgap and @e hgap define extra space between + all children. + */ + wxGridSizer(int rows, int cols, int vgap, int hgap); + wxGridSizer(int cols, int vgap = 0, int hgap = 0); + //@} + + /** + Returns the number of columns in the sizer. + */ + int GetCols(); + + /** + Returns the horizontal gap (in pixels) between cells in the sizer. + */ + int GetHGap(); + + /** + Returns the number of rows in the sizer. + */ + int GetRows(); + + /** + Returns the vertical gap (in pixels) between the cells in the sizer. + */ + int GetVGap(); + + /** + Sets the number of columns in the sizer. + */ + void SetCols(int cols); + + /** + Sets the horizontal gap (in pixels) between cells in the sizer. + */ + void SetHGap(int gap); + + /** + Sets the number of rows in the sizer. + */ + void SetRows(int rows); + + /** + Sets the vertical gap (in pixels) between the cells in the sizer. + */ + void SetVGap(int gap); +}; + + +/** + @class wxStaticBoxSizer + @wxheader{sizer.h} + + wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static + box around the sizer. This static box may be either created independently or + the sizer may create it itself as a convenience. In any case, the sizer owns + the wxStaticBox control and will delete it if it is + deleted. + + @library{wxcore} + @category{winlayout} + + @seealso + wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizeroverview "Sizer overview" +*/ +class wxStaticBoxSizer : public wxBoxSizer +{ +public: + //@{ + /** + The first constructor uses an already existing static box. It takes the + associated static box and the orientation @e orient, which can be either + @c wxVERTICAL or @c wxHORIZONTAL as parameters. + + The second one creates a new static box with the given label and parent window. + */ + wxStaticBoxSizer(wxStaticBox* box, int orient); + wxStaticBoxSizer(int orient, wxWindow parent, + const wxString& label = wxEmptyString); + //@} + + /** + Returns the static box associated with the sizer. + */ + wxStaticBox* GetStaticBox(); +}; + + +/** + @class wxBoxSizer + @wxheader{sizer.h} + + The basic idea behind a box sizer is that windows will most often be laid out + in rather + simple basic geometry, typically in a row or a column or several hierarchies of + either. + + For more information, please see @ref overview_boxsizerprogramming "Programming + with wxBoxSizer". + + @library{wxcore} + @category{winlayout} + + @seealso + wxSizer, @ref overview_sizeroverview "Sizer overview" +*/ +class wxBoxSizer : public wxSizer +{ +public: + /** + Constructor for a wxBoxSizer. @e orient may be either of wxVERTICAL + or wxHORIZONTAL for creating either a column sizer or a row sizer. + */ + wxBoxSizer(int orient); + + /** + Implements the calculation of a box sizer's minimal. It is used internally + only and must not be called by the user. Documented for information. + */ + wxSize CalcMin(); + + /** + Returns the orientation of the box sizer, either wxVERTICAL + or wxHORIZONTAL. + */ + int GetOrientation(); + + /** + Implements the calculation of a box sizer's dimensions and then sets + the size of its children (calling wxWindow::SetSize + if the child is a window). It is used internally only and must not be called + by the user (call Layout() if you want to resize). Documented for information. + */ + void RecalcSizes(); +}; diff --git a/interface/slider.h b/interface/slider.h new file mode 100644 index 0000000000..74df3737ff --- /dev/null +++ b/interface/slider.h @@ -0,0 +1,290 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: slider.h +// Purpose: documentation for wxSlider class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSlider + @wxheader{slider.h} + + A slider is a control with a handle which can be pulled + back and forth to change the value. + + On Windows, the track bar control is used. + + Slider events are handled in the same way as a scrollbar. + + @beginStyleTable + @style{wxSL_HORIZONTAL}: + Displays the slider horizontally (this is the default). + @style{wxSL_VERTICAL}: + Displays the slider vertically. + @style{wxSL_AUTOTICKS}: + Displays tick marks. + @style{wxSL_LABELS}: + Displays minimum, maximum and value labels. + @style{wxSL_LEFT}: + Displays ticks on the left and forces the slider to be vertical. + @style{wxSL_RIGHT}: + Displays ticks on the right and forces the slider to be vertical. + @style{wxSL_TOP}: + Displays ticks on the top. + @style{wxSL_BOTTOM}: + Displays ticks on the bottom (this is the default). + @style{wxSL_SELRANGE}: + Allows the user to select a range on the slider. Windows only. + @style{wxSL_INVERSE}: + Inverses the mininum and maximum endpoints on the slider. Not + compatible with wxSL_SELRANGE. + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{slider.png} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", wxScrollBar +*/ +class wxSlider : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a slider. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param value + Initial position for the slider. + + @param minValue + Minimum slider position. + + @param maxValue + Maximum slider position. + + @param size + Window size. If wxDefaultSize is specified then a default size is + chosen. + + @param style + Window style. See wxSlider. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxSlider(); + wxSlider(wxWindow* parent, wxWindowID id, int value, + int minValue, int maxValue, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSL_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "slider"); + //@} + + /** + Destructor, destroying the slider. + */ + ~wxSlider(); + + /** + Clears the selection, for a slider with the @b wxSL_SELRANGE style. + + @remarks Windows 95 only. + */ + void ClearSel(); + + /** + Clears the ticks. + + @remarks Windows 95 only. + */ + void ClearTicks(); + + /** + Used for two-step slider construction. See wxSlider() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, int value, + int minValue, int maxValue, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSL_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "slider"); + + /** + Returns the line size. + + @sa SetLineSize() + */ + int GetLineSize(); + + /** + Gets the maximum slider value. + + @sa GetMin(), SetRange() + */ + int GetMax(); + + /** + Gets the minimum slider value. + + @sa GetMin(), SetRange() + */ + int GetMin(); + + /** + Returns the page size. + + @sa SetPageSize() + */ + int GetPageSize(); + + /** + Returns the selection end point. + + @remarks Windows 95 only. + + @sa GetSelStart(), SetSelection() + */ + int GetSelEnd(); + + /** + Returns the selection start point. + + @remarks Windows 95 only. + + @sa GetSelEnd(), SetSelection() + */ + int GetSelStart(); + + /** + Returns the thumb length. + + @remarks Windows 95 only. + + @sa SetThumbLength() + */ + int GetThumbLength(); + + /** + Returns the tick frequency. + + @remarks Windows 95 only. + + @sa SetTickFreq() + */ + int GetTickFreq(); + + /** + Gets the current slider value. + + @sa GetMin(), GetMax(), SetValue() + */ + int GetValue(); + + /** + Sets the line size for the slider. + + @param lineSize + The number of steps the slider moves when the user moves it up or down a line. + + @sa GetLineSize() + */ + void SetLineSize(int lineSize); + + /** + Sets the page size for the slider. + + @param pageSize + The number of steps the slider moves when the user pages up or down. + + @sa GetPageSize() + */ + void SetPageSize(int pageSize); + + /** + Sets the minimum and maximum slider values. + + @sa GetMin(), GetMax() + */ + void SetRange(int minValue, int maxValue); + + /** + Sets the selection. + + @param startPos + The selection start position. + + @param endPos + The selection end position. + + @remarks Windows 95 only. + + @sa GetSelStart(), GetSelEnd() + */ + void SetSelection(int startPos, int endPos); + + /** + Sets the slider thumb length. + + @param len + The thumb length. + + @remarks Windows 95 only. + + @sa GetThumbLength() + */ + void SetThumbLength(int len); + + /** + Sets a tick position. + + @param tickPos + The tick position. + + @remarks Windows 95 only. + + @sa SetTickFreq() + */ + void SetTick(int tickPos); + + /** + Sets the tick mark frequency and position. + + @param n + Frequency. For example, if the frequency is set to two, a tick mark is + displayed for + every other increment in the slider's range. + + @param pos + Position. Must be greater than zero. TODO: what is this for? + + @remarks Windows 95 only. + + @sa GetTickFreq() + */ + void SetTickFreq(int n, int pos); + + /** + Sets the slider position. + + @param value + The slider position. + */ + void SetValue(int value); +}; diff --git a/interface/snglinst.h b/interface/snglinst.h new file mode 100644 index 0000000000..2ca73e7293 --- /dev/null +++ b/interface/snglinst.h @@ -0,0 +1,108 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: snglinst.h +// Purpose: documentation for wxSingleInstanceChecker class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSingleInstanceChecker + @wxheader{snglinst.h} + + wxSingleInstanceChecker class allows to check that only a single instance of a + program is running. To do it, you should create an object of this class. As + long as this object is alive, calls to + wxSingleInstanceChecker::IsAnotherRunning from + other processes will return @true. + + As the object should have the life span as big as possible, it makes sense to + create it either as a global or in wxApp::OnInit. For + example: + + @code + bool MyApp::OnInit() + { + const wxString name = wxString::Format("MyApp-%s", wxGetUserId().c_str()); + m_checker = new wxSingleInstanceChecker(name); + if ( m_checker-IsAnotherRunning() ) + { + wxLogError(_("Another program instance is already running, aborting.")); + + delete m_checker; // OnExit() won't be called if we return @false + m_checker = @NULL; + + return @false; + } + + ... more initializations ... + + return @true; + } + + int MyApp::OnExit() + { + delete m_checker; + + return 0; + } + @endcode + + Note using wxGetUserId to construct the name: this + allows different user to run the application concurrently which is usually the + intended goal. If you don't use the user name in the wxSingleInstanceChecker + name, only one user would be able to run the application at a time. + + This class is implemented for Win32 and Unix platforms (supporting @c fcntl() + system call, but almost all of modern Unix systems do) only. + + @library{wxbase} + @category{misc} +*/ +class wxSingleInstanceChecker +{ +public: + /** + Like Create() but without + error checking. + */ + wxSingleInstanceChecker(const wxString& name, + const wxString& path = wxEmptyString); + + /** + Destructor frees the associated resources. + + Note that it is not virtual, this class is not meant to be used polymorphically + */ + ~wxSingleInstanceChecker(); + + /** + Initialize the object if it had been created using the default constructor. + Note that you can't call Create() more than once, so calling it if the + @ref wxsingleinstancechecker() "non default ctor" + had been used is an error. + + @param name + must be given and be as unique as possible. It is used as the + mutex name under Win32 and the lock file name under Unix. + GetAppName() and wxGetUserId() + are commonly used to construct this parameter. + + @param path + is optional and is ignored under Win32 and used as the directory to + create the lock file in under Unix (default is + wxGetHomeDir()) + + @returns Returns @false if initialization failed, it doesn't mean that + another instance is running - use IsAnotherRunning() + to check for it. + */ + bool Create(const wxString& name, + const wxString& path = wxEmptyString); + + /** + Returns @true if another copy of this program is already running, @false + otherwise. + */ + bool IsAnotherRunning(); +}; diff --git a/interface/socket.h b/interface/socket.h new file mode 100644 index 0000000000..99342a4489 --- /dev/null +++ b/interface/socket.h @@ -0,0 +1,1182 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: socket.h +// Purpose: documentation for wxIPV4address class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIPV4address + @wxheader{socket.h} + + + @library{wxbase} + @category{net} +*/ +class wxIPV4address : public wxIPaddress +{ +public: + /** + Set address to any of the addresses of the current machine. Whenever + possible, use this function instead of LocalHost(), + as this correctly handles multi-homed hosts and avoids other small + problems. Internally, this is the same as setting the IP address + to @b INADDR_ANY. + + @returns Returns @true on success, @false if something went wrong. + */ + bool AnyAddress(); + + //@{ + /** + Returns the hostname which matches the IP address. + */ + bool Hostname(const wxString& hostname); + Return value wxString Hostname(); + //@} + + /** + Returns a wxString containing the IP address in dot quad (127.0.0.1) format. + */ + wxString IPAddress(); + + /** + Set address to localhost (127.0.0.1). Whenever possible, use the + AnyAddress(), + function instead of this one, as this will correctly handle multi-homed + hosts and avoid other small problems. + */ + bool LocalHost(); + + //@{ + /** + Returns the current service. + */ + bool Service(const wxString& service); + Return value bool Service(unsigned short service); + Return value unsigned short Service(); + //@} +}; + + +/** + @class wxSocketServer + @wxheader{socket.h} + + + @library{wxnet} + @category{net} + + @seealso + wxSocketServer::WaitForAccept, wxSocketBase::SetNotify, wxSocketBase::Notify, + wxSocketServer::AcceptWith +*/ +class wxSocketServer : public wxSocketBase +{ +public: + /** + Constructs a new server and tries to bind to the specified @e address. + Before trying to accept new connections, test whether it succeeded with + @ref wxSocketBase::isok wxSocketBase:IsOk. + + @param address + Specifies the local address for the server (e.g. port number). + + @param flags + Socket flags (See wxSocketBase::SetFlags) + */ + wxSocketServer(const wxSockAddress& address, + wxSocketFlags flags = wxSOCKET_NONE); + + /** + Destructor (it doesn't close the accepted connections). + */ + ~wxSocketServer(); + + /** + Accepts an incoming connection request, and creates a new + wxSocketBase object which represents + the server-side of the connection. + + If @e wait is @true and there are no pending connections to be + accepted, it will wait for the next incoming connection to + arrive. @b Warning: This will block the GUI. + + If @e wait is @false, it will try to accept a pending connection + if there is one, but it will always return immediately without blocking + the GUI. If you want to use Accept in this way, you can either check for + incoming connections with WaitForAccept() + or catch @b wxSOCKET_CONNECTION events, then call Accept once you know + that there is an incoming connection waiting to be accepted. + + @returns Returns an opened socket connection, or @NULL if an error + occurred or if the wait parameter was @false and there + were no pending connections. + + @sa WaitForAccept(), wxSocketBase::SetNotify, + wxSocketBase::Notify, AcceptWith() + */ + wxSocketBase * Accept(bool wait = @true); + + /** + Accept an incoming connection using the specified socket object. + + @param socket + Socket to be initialized + + @returns Returns @true on success, or @false if an error occurred or if the + wait parameter was @false and there were no pending + connections. + */ + bool AcceptWith(wxSocketBase& socket, bool wait = @true); + + /** + This function waits for an incoming connection. Use it if you want to call + Accept() or AcceptWith() + with @e wait set to @false, to detect when an incoming connection is waiting + to be accepted. + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + + @param millisecond + Number of milliseconds to wait. + + @returns Returns @true if an incoming connection arrived, @false if the + timeout elapsed. + */ + bool WaitForAccept(long seconds = -1, long millisecond = 0); +}; + + +/** + @class wxIPaddress + @wxheader{socket.h} + + wxIPaddress is an abstract base class for all internet protocol address + objects. Currently, only wxIPV4address + is implemented. An experimental implementation for IPV6, wxIPV6address, + is being developed. + + @library{wxbase} + @category{net} +*/ +class wxIPaddress : public wxSockAddress +{ +public: + /** + Internally, this is the same as setting the IP address + to @b INADDR_ANY. + + On IPV4 implementations, 0.0.0.0 + + On IPV6 implementations, :: + + @returns Returns @true on success, @false if something went wrong. + */ + virtual bool AnyAddress(); + + /** + Internally, this is the same as setting the IP address + to @b INADDR_BROADCAST. + + On IPV4 implementations, 255.255.255.255 + + @returns Returns @true on success, @false if something went wrong. + */ + virtual bool BroadcastAddress(); + + //@{ + /** + Returns the hostname which matches the IP address. + */ + virtual bool Hostname(const wxString& hostname); + Return value virtual wxString Hostname(); + //@} + + /** + Returns a wxString containing the IP address. + */ + virtual wxString IPAddress(); + + /** + Determines if current address is set to localhost. + */ + virtual bool IsLocalHost(); + + /** + Set address to localhost. + + On IPV4 implementations, 127.0.0.1 + + On IPV6 implementations, ::1 + + @returns Returns @true on success, @false if something went wrong. + */ + virtual bool LocalHost(); + + //@{ + /** + Returns the current service. + */ + virtual bool Service(const wxString& service); + Return value virtual bool Service(unsigned short service); + Return value virtual unsigned short Service(); + //@} +}; + + +/** + @class wxSocketClient + @wxheader{socket.h} + + + @library{wxnet} + @category{net} + + @seealso + wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify, wxSocketBase::Notify +*/ +class wxSocketClient : public wxSocketBase +{ +public: + /** + Constructor. + + @param flags + Socket flags (See wxSocketBase::SetFlags) + */ + wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE); + + /** + Destructor. Please see wxSocketBase::Destroy. + */ + ~wxSocketClient(); + + //@{ + /** + Connects to a server using the specified address. + + If @e wait is @true, Connect will wait until the connection + completes. @b Warning: This will block the GUI. + + If @e wait is @false, Connect will try to establish the connection and + return immediately, without blocking the GUI. When used this way, even if + Connect returns @false, the connection request can be completed later. + To detect this, use WaitOnConnect(), + or catch @b wxSOCKET_CONNECTION events (for successful establishment) + and @b wxSOCKET_LOST events (for connection failure). + + @param address + Address of the server. + + @param local + Bind to the specified local address and port before connecting. + The local address and port can also be set using SetLocal, + and then using the 2-parameter Connect method. + + @param wait + If @true, waits for the connection to complete. + + @returns Returns @true if the connection is established and no error + occurs. + + @sa WaitOnConnect(), wxSocketBase::SetNotify, + wxSocketBase::Notify + */ + bool Connect(wxSockAddress& address, bool wait = @true); + bool Connect(wxSockAddress& address, wxSockAddress& local, + bool wait = @true); + //@} + + /** + Wait until a connection request completes, or until the specified timeout + elapses. Use this function after issuing a call + to Connect() with @e wait set to @false. + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + + @param millisecond + Number of milliseconds to wait. + + @returns WaitOnConnect returns @true if the connection request completes. + This does not necessarily mean that the connection + was successfully established; it might also happen + that the connection was refused by the peer. Use + IsConnected to distinguish between these two + situations. + */ + bool WaitOnConnect(long seconds = -1, long milliseconds = 0); +}; + + +/** + @class wxSockAddress + @wxheader{socket.h} + + You are unlikely to need to use this class: only wxSocketBase uses it. + + @library{wxbase} + @category{FIXME} + + @seealso + wxSocketBase, wxIPaddress, wxIPV4address +*/ +class wxSockAddress : public wxObject +{ +public: + /** + Default constructor. + */ + wxSockAddress(); + + /** + Default destructor. + */ + ~wxSockAddress(); + + /** + Delete all informations about the address. + */ + void Clear(); + + /** + Returns the length of the socket address. + */ + int SockAddrLen(); +}; + + +/** + @class wxSocketEvent + @wxheader{socket.h} + + This event class contains information about socket events. + + @library{wxnet} + @category{net} + + @seealso + wxSocketBase, wxSocketClient, wxSocketServer +*/ +class wxSocketEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxSocketEvent(int id = 0); + + /** + Gets the client data of the socket which generated this event, as + set with wxSocketBase::SetClientData. + */ + void * GetClientData(); + + /** + Returns the socket object to which this event refers to. This makes + it possible to use the same event handler for different sockets. + */ + wxSocketBase * GetSocket(); + + /** + Returns the socket event type. + */ + wxSocketNotify GetSocketEvent(); +}; + + +/** + @class wxSocketBase + @wxheader{socket.h} + + wxSocketBase is the base class for all socket-related objects, and it + defines all basic IO functionality. + + Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x) + If you want to use sockets or derived classes such as wxFTP in a secondary + thread, + call wxSocketBase::Initialize() (undocumented) from the main thread before + creating + any sockets - in wxApp::OnInit for example. + See http://wiki.wxwidgets.org/wiki.pl?WxSocket or + http://www.litwindow.com/knowhow/knowhow.html for more details. + + @library{wxnet} + @category{net} + + @seealso + wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets + "Sockets sample" +*/ +class wxSocketBase : public wxObject +{ +public: + /** + Default constructor. Don't use it directly; instead, use + wxSocketClient to construct a socket client, or + wxSocketServer to construct a socket server. + */ + wxSocketBase(); + + /** + Destructor. Do not destroy a socket using the delete operator directly; + use Destroy() instead. Also, do not create + socket objects in the stack. + */ + ~wxSocketBase(); + + /** + Functions that perform basic IO functionality. + + Close() + + Discard() + + Peek() + + Read() + + ReadMsg() + + Unread() + + Write() + + WriteMsg() + + Functions that perform a timed wait on a certain IO condition. + + InterruptWait() + + Wait() + + WaitForLost() + + WaitForRead() + + WaitForWrite() + and also: + + wxSocketServer::WaitForAccept + + wxSocketClient::WaitOnConnect + + Functions that allow applications to customize socket IO as needed. + + GetFlags() + + SetFlags() + + SetTimeout() + + SetLocal() + */ + + + /** + This function shuts down the socket, disabling further transmission and + reception of data; it also disables events for the socket and frees the + associated system resources. Upon socket destruction, Close is automatically + called, so in most cases you won't need to do it yourself, unless you + explicitly want to shut down the socket, typically to notify the peer + that you are closing the connection. + */ + void Close(); + + /** + @ref construct() wxSocketBase + + @ref destruct() ~wxSocketBase + + Destroy() + */ + + + /** + Destroys the socket safely. Use this function instead of the delete operator, + since otherwise socket events could reach the application even after the + socket has been destroyed. To prevent this problem, this function appends + the wxSocket to a list of object to be deleted on idle time, after all + events have been processed. For the same reason, you should avoid creating + socket objects in the stack. + + Destroy calls Close() automatically. + + @returns Always @true. + */ + bool Destroy(); + + /** + This function simply deletes all bytes in the incoming queue. This function + always returns immediately and its operation is not affected by IO flags. + + Use LastCount() to verify the number of bytes actually discarded. + + If you use Error(), it will always return @false. + */ + wxSocketBase Discard(); + + /** + Returns @true if an error occurred in the last IO operation. + + Use this function to check for an error condition after one of the + following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg. + */ + bool Error(); + + /** + Returns a pointer of the client data for this socket, as set with + SetClientData() + */ + void * GetClientData(); + + /** + Returns current IO flags, as set with SetFlags() + */ + wxSocketFlags GetFlags(); + + /** + This function returns the local address field of the socket. The local + address field contains the complete local address of the socket (local + address, local port, ...). + + @returns @true if no error happened, @false otherwise. + */ + bool GetLocal(wxSockAddress& addr); + + /** + This function returns the peer address field of the socket. The peer + address field contains the complete peer host address of the socket + (address, port, ...). + + @returns @true if no error happened, @false otherwise. + */ + bool GetPeer(wxSockAddress& addr); + + /** + Functions that allow applications to receive socket events. + + Notify() + + SetNotify() + + GetClientData() + + SetClientData() + + SetEventHandler() + */ + + + /** + Use this function to interrupt any wait operation currently in progress. + Note that this is not intended as a regular way to interrupt a Wait call, + but only as an escape mechanism for exceptional situations where it is + absolutely necessary to use it, for example to abort an operation due to + some exception or abnormal problem. InterruptWait is automatically called + when you Close() a socket (and thus also upon + socket destruction), so you don't need to use it in these cases. + + Wait(), + wxSocketServer::WaitForAccept, + WaitForLost(), + WaitForRead(), + WaitForWrite(), + wxSocketClient::WaitOnConnect + */ + void InterruptWait(); + + /** + Returns @true if the socket is connected. + */ + bool IsConnected(); + + /** + This function waits until the socket is readable. This might mean that + queued data is available for reading or, for streamed sockets, that + the connection has been closed, so that a read operation will complete + immediately without blocking (unless the @b wxSOCKET_WAITALL flag + is set, in which case the operation might still block). + */ + bool IsData(); + + /** + Returns @true if the socket is not connected. + */ + bool IsDisconnected(); + + /** + Returns @true if the socket is initialized and ready and @false in other + cases. + */ +#define bool IsOk() /* implementation is private */ + + /** + Returns the number of bytes read or written by the last IO call. + + Use this function to get the number of bytes actually transferred + after using one of the following IO calls: Discard, Peek, Read, + ReadMsg, Unread, Write, WriteMsg. + */ + wxUint32 LastCount(); + + /** + Returns the last wxSocket error. See @ref overview_wxsocketbase "wxSocket + errors". + + Please note that this function merely returns the last error code, + but it should not be used to determine if an error has occurred (this + is because successful operations do not change the LastError value). + Use Error() first, in order to determine + if the last IO call failed. If this returns @true, use LastError + to discover the cause of the error. + */ + wxSocketError LastError(); + + /** + According to the @e notify value, this function enables + or disables socket events. If @e notify is @true, the events + configured with SetNotify() will + be sent to the application. If @e notify is @false; no events + will be sent. + */ + void Notify(bool notify); + + /** + This function peeks a buffer of @e nbytes bytes from the socket. + Peeking a buffer doesn't delete it from the socket input queue. + + Use LastCount() to verify the number of bytes actually peeked. + + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer where to put peeked data. + + @param nbytes + Number of bytes. + + @returns Returns a reference to the current object. + + @sa Error(), LastError(), LastCount(), + SetFlags() + */ + wxSocketBase Peek(void * buffer, wxUint32 nbytes); + + /** + This function reads a buffer of @e nbytes bytes from the socket. + + Use LastCount() to verify the number of bytes actually read. + + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer where to put read data. + + @param nbytes + Number of bytes. + + @returns Returns a reference to the current object. + + @sa Error(), LastError(), LastCount(), + SetFlags() + */ + wxSocketBase Read(void * buffer, wxUint32 nbytes); + + /** + This function reads a buffer sent by WriteMsg() + on a socket. If the buffer passed to the function isn't big enough, the + remaining bytes will be discarded. This function always waits for the + buffer to be entirely filled, unless an error occurs. + + Use LastCount() to verify the number of bytes actually read. + + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer where to put read data. + + @param nbytes + Size of the buffer. + + @returns Returns a reference to the current object. + + @sa Error(), LastError(), LastCount(), + SetFlags(), WriteMsg() + */ + wxSocketBase ReadMsg(void * buffer, wxUint32 nbytes); + + /** + This function restores the previous state of the socket, as saved + with SaveState() + + Calls to SaveState and RestoreState can be nested. + + @sa SaveState() + */ + void RestoreState(); + + /** + This function saves the current state of the socket in a stack. Socket + state includes flags, as set with SetFlags(), + event mask, as set with SetNotify() and + Notify(), user data, as set with + SetClientData(). + + Calls to SaveState and RestoreState can be nested. + + @sa RestoreState() + */ + void SaveState(); + + /** + Sets user-supplied client data for this socket. All socket events will + contain a pointer to this data, which can be retrieved with + the wxSocketEvent::GetClientData function. + */ + void SetClientData(void * data); + + /** + Sets an event handler to be called when a socket event occurs. The + handler will be called for those events for which notification is + enabled with SetNotify() and + Notify(). + + @param handler + Specifies the event handler you want to use. + + @param id + The id of socket event. + + @sa SetNotify(), Notify(), wxSocketEvent, wxEvtHandler + */ + void SetEventHandler(wxEvtHandler& handler, int id = -1); + + /** + Use SetFlags to customize IO operation for this socket. + The @e flags parameter may be a combination of flags ORed together. + The following flags can be used: + + + @b wxSOCKET_NONE + + + Normal functionality. + + @b wxSOCKET_NOWAIT + + + Read/write as much data as possible and return immediately. + + @b wxSOCKET_WAITALL + + + Wait for all required data to be read/written unless an error occurs. + + @b wxSOCKET_BLOCK + + + Block the GUI (do not yield) while reading/writing data. + + @b wxSOCKET_REUSEADDR + + + Allows the use of an in-use port (wxServerSocket only) + + @b wxSOCKET_BROADCAST + + + Switches the socket to broadcast mode + + @b wxSOCKET_NOBIND + + + Stops the socket from being bound to a specific adapter (normally used in + conjunction with @b wxSOCKET_BROADCAST) + + A brief overview on how to use these flags follows. + + If no flag is specified (this is the same as @b wxSOCKET_NONE), + IO calls will return after some data has been read or written, even + when the transfer might not be complete. This is the same as issuing + exactly one blocking low-level call to recv() or send(). Note + that @e blocking here refers to when the function returns, not + to whether the GUI blocks during this time. + + If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately. + Read operations will retrieve only available data. Write operations will + write as much data as possible, depending on how much space is available + in the output buffer. This is the same as issuing exactly one nonblocking + low-level call to recv() or send(). Note that @e nonblocking here + refers to when the function returns, not to whether the GUI blocks during + this time. + + If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL + the data has been read or written (or until an error occurs), blocking if + necessary, and issuing several low level calls if necessary. This is the + same as having a loop which makes as many blocking low-level calls to + recv() or send() as needed so as to transfer all the data. Note + that @e blocking here refers to when the function returns, not + to whether the GUI blocks during this time. + + The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during + IO operations. If this flag is specified, the socket will not yield + during IO calls, so the GUI will remain blocked until the operation + completes. If it is not used, then the application must take extra + care to avoid unwanted reentrance. + + The @b wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard + setsockopt() flag. This flag allows the socket to bind to a port that is + already in use. + This is mostly used on UNIX-based systems to allow rapid starting and stopping + of a server - + otherwise you may have to wait several minutes for the port to become available. + wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a + particular local port + for an outgoing connection. + This option can have surprising platform dependent behavior, so check the + documentation for + your platform's implementation of setsockopt(). Note that on BSD-based systems + (e.g. Mac OS X), + use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to + be consistent + with Windows. + + The @b wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard + setsockopt() flag. This flag allows the socket to use the broadcast address, + and is generally + used in conjunction with @b wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress. + + So: + + @b wxSOCKET_NONE will try to read at least SOME data, no matter how much. + + @b wxSOCKET_NOWAIT will always return immediately, even if it cannot + read or write ANY data. + + @b wxSOCKET_WAITALL will only return when it has read or written ALL + the data. + + @b wxSOCKET_BLOCK has nothing to do with the previous flags and + it controls whether the GUI blocks. + + @b wxSOCKET_REUSEADDR controls special platform-specific behavior for + reusing local addresses/ports. + */ + void SetFlags(wxSocketFlags flags); + + /** + This function allows you to set the local address and port, + useful when an application needs to reuse a particular port. When + a local port is set for a wxSocketClient, + @b bind will be called before @b connect. + */ + bool SetLocal(wxIPV4address& local); + + /** + SetNotify specifies which socket events are to be sent to the event handler. + The @e flags parameter may be combination of flags ORed together. The + following flags can be used: + + + @b wxSOCKET_INPUT_FLAG + + + to receive wxSOCKET_INPUT + + @b wxSOCKET_OUTPUT_FLAG + + + to receive wxSOCKET_OUTPUT + + @b wxSOCKET_CONNECTION_FLAG + + + to receive wxSOCKET_CONNECTION + + @b wxSOCKET_LOST_FLAG + + + to receive wxSOCKET_LOST + + For example: + In this example, the user will be notified about incoming socket data and + whenever the connection is closed. + + For more information on socket events see @ref overview_wxsocketbase "wxSocket + events". + */ + void SetNotify(wxSocketEventFlags flags); + + /** + This function sets the default socket timeout in seconds. This timeout + applies to all IO calls, and also to the Wait() family + of functions if you don't specify a wait interval. Initially, the default + timeout is 10 minutes. + */ + void SetTimeout(int seconds); + + /** + Functions to retrieve current state and miscellaneous info. + + Error() + + GetLocal() + + GetPeer() + IsConnected() + + IsData() + + IsDisconnected() + + LastCount() + + LastError() + + IsOk() + + SaveState() + + RestoreState() + */ + + + /** + This function unreads a buffer. That is, the data in the buffer is put back + in the incoming queue. This function is not affected by wxSocket flags. + + If you use LastCount(), it will always return @e nbytes. + + If you use Error(), it will always return @false. + + @param buffer + Buffer to be unread. + + @param nbytes + Number of bytes. + + @returns Returns a reference to the current object. + + @sa Error(), LastCount(), LastError() + */ + wxSocketBase Unread(const void * buffer, wxUint32 nbytes); + + /** + This function waits until any of the following conditions is @true: + + + The socket becomes readable. + The socket becomes writable. + An ongoing connection request has completed (wxSocketClient only) + An incoming connection request has arrived (wxSocketServer only) + The connection has been closed. + + Note that it is recommended to use the individual Wait functions + to wait for the required condition, instead of this one. + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + + @param millisecond + Number of milliseconds to wait. + + @returns Returns @true when any of the above conditions is satisfied, + @false if the timeout was reached. + + @sa InterruptWait(), wxSocketServer::WaitForAccept, + WaitForLost(), WaitForRead(), + WaitForWrite(), wxSocketClient::WaitOnConnect + */ + bool Wait(long seconds = -1, long millisecond = 0); + + /** + This function waits until the connection is lost. This may happen if + the peer gracefully closes the connection or if the connection breaks. + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + + @param millisecond + Number of milliseconds to wait. + + @returns Returns @true if the connection was lost, @false if the timeout + was reached. + + @sa InterruptWait(), Wait() + */ + bool Wait(long seconds = -1, long millisecond = 0); + + /** + This function waits until the socket is readable. This might mean that + queued data is available for reading or, for streamed sockets, that + the connection has been closed, so that a read operation will complete + immediately without blocking (unless the @b wxSOCKET_WAITALL flag + is set, in which case the operation might still block). + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + + @param millisecond + Number of milliseconds to wait. + + @returns Returns @true if the socket becomes readable, @false on timeout. + + @sa InterruptWait(), Wait() + */ + bool WaitForRead(long seconds = -1, long millisecond = 0); + + /** + This function waits until the socket becomes writable. This might mean that + the socket is ready to send new data, or for streamed sockets, that the + connection has been closed, so that a write operation is guaranteed to + complete immediately (unless the @b wxSOCKET_WAITALL flag is set, + in which case the operation might still block). + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + + @param millisecond + Number of milliseconds to wait. + + @returns Returns @true if the socket becomes writable, @false on timeout. + + @sa InterruptWait(), Wait() + */ + bool WaitForWrite(long seconds = -1, long millisecond = 0); + + /** + This function writes a buffer of @e nbytes bytes to the socket. + + Use LastCount() to verify the number of bytes actually written. + + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer with the data to be sent. + + @param nbytes + Number of bytes. + + @returns Returns a reference to the current object. + + @sa Error(), LastError(), LastCount(), + SetFlags() + */ + wxSocketBase Write(const void * buffer, wxUint32 nbytes); + + /** + This function writes a buffer of @e nbytes bytes from the socket, but it + writes a short header before so that ReadMsg() + knows how much data should it actually read. So, a buffer sent with WriteMsg + @b must be read with ReadMsg. This function always waits for the entire + buffer to be sent, unless an error occurs. + + Use LastCount() to verify the number of bytes actually written. + + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer with the data to be sent. + + @param nbytes + Number of bytes to send. + + @returns Returns a reference to the current object. + */ + wxSocketBase WriteMsg(const void * buffer, wxUint32 nbytes); +}; + + +/** + @class wxDatagramSocket + @wxheader{socket.h} + + + @library{wxnet} + @category{FIXME} + + @seealso + wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, + wxSocketBase::SetFlags, +*/ +class wxDatagramSocket : public wxSocketBase +{ +public: + /** + Constructor. + + @param flags + Socket flags (See wxSocketBase::SetFlags) + */ + wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE); + + /** + Destructor. Please see wxSocketBase::Destroy. + */ + ~wxDatagramSocket(); + + /** + This function reads a buffer of @e nbytes bytes from the socket. + + Use wxSocketBase::LastCount to verify the number of bytes actually read. + + Use wxSocketBase::Error to determine if the operation succeeded. + + @param address + Any address - will be overwritten with the address of the peer that sent that + data. + + @param buffer + Buffer where to put read data. + + @param nbytes + Number of bytes. + + @returns Returns a reference to the current object, and the address of + the peer that sent the data on address param. + + @sa wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, + wxSocketBase::SetFlags, + */ + wxDatagramSocket ReceiveFrom(wxSockAddress& address, + void * buffer, + wxUint32 nbytes); + + /** + This function writes a buffer of @e nbytes bytes to the socket. + + Use wxSocketBase::LastCount to verify the number of bytes actually wrote. + + Use wxSocketBase::Error to determine if the operation succeeded. + + @param address + The address of the destination peer for this data. + + @param buffer + Buffer where read data is. + + @param nbytes + Number of bytes. + + @returns Returns a reference to the current object. + */ + wxDatagramSocket SendTo(const wxSockAddress& address, + const void * buffer, + wxUint32 nbytes); +}; diff --git a/interface/sound.h b/interface/sound.h new file mode 100644 index 0000000000..94112602e5 --- /dev/null +++ b/interface/sound.h @@ -0,0 +1,113 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sound.h +// Purpose: documentation for wxSound class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSound + @wxheader{sound.h} + + This class represents a short sound (loaded from Windows WAV file), that + can be stored in memory and played. Currently this class is implemented + on Windows and Unix (and uses either + Open Sound System or + Simple DirectMedia Layer). + + @library{wxadv} + @category{FIXME} +*/ +class wxSound : public wxObject +{ +public: + //@{ + /** + Constructs a wave object from a file or, under Windows, from a Windows + resource. Call IsOk() to determine whether this + succeeded. + + @param fileName + The filename or Windows resource. + + @param isResource + @true if fileName is a resource, @false if it is a filename. + */ + wxSound(); + wxSound(const wxString& fileName, bool isResource = @false); + //@} + + /** + Destroys the wxSound object. + */ + ~wxSound(); + + /** + Constructs a wave object from a file or resource. + + @param fileName + The filename or Windows resource. + + @param isResource + @true if fileName is a resource, @false if it is a filename. + + @returns @true if the call was successful, @false otherwise. + */ + bool Create(const wxString& fileName, bool isResource = @false); + + /** + Returns @true if the object contains a successfully loaded file or resource, + @false otherwise. + */ +#define bool IsOk() /* implementation is private */ + + /** + Returns @true if a sound is played at the moment. + + This method is currently not implemented under Windows. + */ + static bool IsPlaying(); + + //@{ + /** + Plays the sound file. If another sound is playing, it will be interrupted. + Returns @true on success, @false otherwise. Note that in general it is + possible + to delete the object which is being asynchronously played any time after + calling this function and the sound would continue playing, however this + currently doesn't work under Windows for sound objects loaded from memory data. + + The possible values for @e flags are: + + wxSOUND_SYNC + + + @c Play will block and wait until the sound is + replayed. + + wxSOUND_ASYNC + + + Sound is played asynchronously, + @c Play returns immediately + + wxSOUND_ASYNC | wxSOUND_LOOP + + + Sound is played asynchronously + and loops until another sound is played, + Stop() is called or the program terminates. + + The static form is shorthand for this code: + */ + bool Play(unsigned flags = wxSOUND_ASYNC); + static bool Play(const wxString& filename, + unsigned flags = wxSOUND_ASYNC); + //@} + + /** + If a sound is played, this function stops it. + */ + static void Stop(); +}; diff --git a/interface/spinbutt.h b/interface/spinbutt.h new file mode 100644 index 0000000000..2ad7a6b82a --- /dev/null +++ b/interface/spinbutt.h @@ -0,0 +1,169 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: spinbutt.h +// Purpose: documentation for wxSpinEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSpinEvent + @wxheader{spinbutt.h} + + This event class is used for the events generated by + wxSpinButton and wxSpinCtrl. + + @library{wxcore} + @category{events} + + @seealso + wxSpinButton and wxSpinCtrl +*/ +class wxSpinEvent : public wxNotifyEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxSpinEvent(wxEventType commandType = wxEVT_@NULL, int id = 0); + + /** + Retrieve the current spin button or control value. + */ + int GetPosition(); + + /** + Set the value associated with the event. + */ + void SetPosition(int pos); +}; + + +/** + @class wxSpinButton + @wxheader{spinbutt.h} + + A wxSpinButton has two small up and down (or left and right) arrow buttons. It + is often used next to a text control for increment and decrementing a value. + Portable programs should try to use wxSpinCtrl instead + as wxSpinButton is not implemented for all platforms but wxSpinCtrl is as it + degenerates to a simple wxTextCtrl on such platforms. + + @b NB: the range supported by this control (and wxSpinCtrl) depends on the + platform but is at least @c -0x8000 to @c 0x7fff. Under GTK and + Win32 with sufficiently new version of @c comctrl32.dll (at least 4.71 is + required, 5.80 is recommended) the full 32 bit range is supported. + + @beginStyleTable + @style{wxSP_HORIZONTAL}: + Specifies a horizontal spin button (note that this style is not + supported in wxGTK). + @style{wxSP_VERTICAL}: + Specifies a vertical spin button. + @style{wxSP_ARROW_KEYS}: + The user can use arrow keys to change the value. + @style{wxSP_WRAP}: + The value wraps at the minimum and maximum. + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{spinbutton.png} + + @seealso + wxSpinCtrl +*/ +class wxSpinButton : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a spin button. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. If wxDefaultPosition is specified then a default position + is chosen. + + @param size + Window size. If wxDefaultSize is specified then a default size is + chosen. + + @param style + Window style. See wxSpinButton. + + @param name + Window name. + + @sa Create() + */ + wxSpinButton(); + wxSpinButton(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_HORIZONTAL, + const wxString& name = "spinButton"); + //@} + + /** + Destructor, destroys the spin button control. + */ + ~wxSpinButton(); + + /** + Scrollbar creation function called by the spin button constructor. + See wxSpinButton() for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_HORIZONTAL, + const wxString& name = "spinButton"); + + /** + Returns the maximum permissible value. + + @sa SetRange() + */ + int GetMax(); + + /** + Returns the minimum permissible value. + + @sa SetRange() + */ + int GetMin(); + + /** + Returns the current spin button value. + + @sa SetValue() + */ + int GetValue(); + + /** + Sets the range of the spin button. + + @param min + The minimum value for the spin button. + + @param max + The maximum value for the spin button. + + @sa GetMin(), GetMax() + */ + void SetRange(int min, int max); + + /** + Sets the value of the spin button. + + @param value + The value for the spin button. + */ + void SetValue(int value); +}; diff --git a/interface/spinctrl.h b/interface/spinctrl.h new file mode 100644 index 0000000000..5513dbb06e --- /dev/null +++ b/interface/spinctrl.h @@ -0,0 +1,136 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: spinctrl.h +// Purpose: documentation for wxSpinCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSpinCtrl + @wxheader{spinctrl.h} + + wxSpinCtrl combines wxTextCtrl and + wxSpinButton in one control. + + @beginStyleTable + @style{wxSP_ARROW_KEYS}: + The user can use arrow keys to change the value. + @style{wxSP_WRAP}: + The value wraps at the minimum and maximum. + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{spinctrl.png} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", wxSpinButton, + wxControl +*/ +class wxSpinCtrl : public wxControl +{ +public: + //@{ + /** + ) + + Constructor, creating and showing a spin control. + + @param parent + Parent window. Must not be @NULL. + + @param value + Default value. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. If wxDefaultPosition is specified then a default position + is chosen. + + @param size + Window size. If wxDefaultSize is specified then a default size is + chosen. + + @param style + Window style. See wxSpinButton. + + @param min + Minimal value. + + @param max + Maximal value. + + @param initial + Initial value. + + @param name + Window name. + + @sa Create() + */ + wxSpinCtrl(); + wxSpinCtrl(wxWindow* parent, wxWindowID id = -1, + const wxString& value = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_ARROW_KEYS, + int min = 0, int max = 100, + int initial = 0); + //@} + + /** + ) + + Creation function called by the spin control constructor. + + See wxSpinCtrl() for details. + */ + bool Create(wxWindow* parent, wxWindowID id = -1, + const wxString& value = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_ARROW_KEYS, + int min = 0, int max = 100, + int initial = 0); + + /** + Gets maximal allowable value. + */ + int GetMax(); + + /** + Gets minimal allowable value. + */ + int GetMin(); + + /** + Gets the value of the spin control. + */ + int GetValue(); + + /** + Sets range of allowable values. + */ + void SetRange(int minVal, int maxVal); + + /** + Select the text in the text part of the control between positions + @e from (inclusive) and @e to (exclusive). This is similar to + wxTextCtrl::SetSelection. + + @b NB: this is currently only implemented for Windows and generic versions + of the control. + */ + void SetSelection(long from, long to); + + //@{ + /** + Sets the value of the spin control. + */ + void SetValue(const wxString& text); + void SetValue(int value); + //@} +}; diff --git a/interface/splash.h b/interface/splash.h new file mode 100644 index 0000000000..7a9bfb2ec4 --- /dev/null +++ b/interface/splash.h @@ -0,0 +1,88 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: splash.h +// Purpose: documentation for wxSplashScreen class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSplashScreen + @wxheader{splash.h} + + wxSplashScreen shows a window with a thin border, displaying a bitmap + describing your + application. Show it in application initialisation, and then either explicitly + destroy + it or let it time-out. + + Example usage: + + @code + wxBitmap bitmap; + if (bitmap.LoadFile("splash16.png", wxBITMAP_TYPE_PNG)) + { + wxSplashScreen* splash = new wxSplashScreen(bitmap, + wxSPLASH_CENTRE_ON_SCREEN|wxSPLASH_TIMEOUT, + 6000, @NULL, -1, wxDefaultPosition, wxDefaultSize, + wxBORDER_SIMPLE|wxSTAY_ON_TOP); + } + wxYield(); + @endcode + + @library{wxadv} + @category{managedwnd} +*/ +class wxSplashScreen : public wxFrame +{ +public: + /** + Construct the splash screen passing a bitmap, a style, a timeout, a window id, + optional position + and size, and a window style. + + @e splashStyle is a bitlist of some of the following: + + wxSPLASH_CENTRE_ON_PARENT + wxSPLASH_CENTRE_ON_SCREEN + wxSPLASH_NO_CENTRE + wxSPLASH_TIMEOUT + wxSPLASH_NO_TIMEOUT + + @e milliseconds is the timeout in milliseconds. + */ + wxSplashScreen(const wxBitmap& bitmap, long splashStyle, + int milliseconds, + wxWindow* parent, + wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBORDER_SIMPLE|wxFRAME_NO_TASKBAR|wxSTAY_ON_TOP); + + /** + Destroys the splash screen. + */ + ~wxSplashScreen(); + + /** + Returns the splash style (see wxSplashScreen() for + details). + */ + long GetSplashStyle(); + + /** + Returns the window used to display the bitmap. + */ + wxSplashScreenWindow* GetSplashWindow(); + + /** + Returns the timeout in milliseconds. + */ + int GetTimeout(); + + /** + Reimplement this event handler if you want to set an application variable on + window destruction, for example. + */ + void OnCloseWindow(wxCloseEvent& event); +}; diff --git a/interface/splitter.h b/interface/splitter.h new file mode 100644 index 0000000000..acdb17b0ce --- /dev/null +++ b/interface/splitter.h @@ -0,0 +1,457 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: splitter.h +// Purpose: documentation for wxSplitterWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSplitterWindow + @wxheader{splitter.h} + + @ref overview_wxsplitterwindowoverview "wxSplitterWindow overview" + + This class manages up to two subwindows. The current view can be + split into two programmatically (perhaps from a menu command), and unsplit + either programmatically or via the wxSplitterWindow user interface. + + @beginStyleTable + @style{wxSP_3D}: + Draws a 3D effect border and sash. + @style{wxSP_3DSASH}: + Draws a 3D effect sash. + @style{wxSP_3DBORDER}: + Synonym for wxSP_BORDER. + @style{wxSP_BORDER}: + Draws a standard border. + @style{wxSP_NOBORDER}: + No border (default). + @style{wxSP_NO_XP_THEME}: + Under Windows XP, switches off the attempt to draw the splitter + using Windows XP theming, so the borders and sash will take on the + pre-XP look. + @style{wxSP_PERMIT_UNSPLIT}: + Always allow to unsplit, even with the minimum pane size other than + zero. + @style{wxSP_LIVE_UPDATE}: + Don't draw XOR line but resize the child windows immediately. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @seealso + wxSplitterEvent +*/ +class wxSplitterWindow : public wxWindow +{ +public: + //@{ + /** + Constructor for creating the window. + + @param parent + The parent of the splitter window. + + @param id + The window identifier. + + @param pos + The window position. + + @param size + The window size. + + @param style + The window style. See wxSplitterWindow. + + @param name + The window name. + + @remarks After using this constructor, you must create either one or two + subwindows with the splitter window as parent, and + then call one of Initialize(), + SplitVertically() and + SplitHorizontally() in order to set + the pane(s). + + @sa Initialize(), SplitVertically(), + SplitHorizontally(), Create() + */ + wxSplitterWindow(); + wxSplitterWindow(wxWindow* parent, wxWindowID id, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style=wxSP_3D, + const wxString& name = "splitterWindow"); + //@} + + /** + Destroys the wxSplitterWindow and its children. + */ + ~wxSplitterWindow(); + + /** + Creation function, for two-step construction. See wxSplitterWindow() for + details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style=wxSP_3D, + const wxString& name = "splitterWindow"); + + /** + Returns the current minimum pane size (defaults to zero). + + @sa SetMinimumPaneSize() + */ + int GetMinimumPaneSize(); + + /** + Returns the current sash gravity. + + @sa SetSashGravity() + */ + double GetSashGravity(); + + /** + Returns the current sash position. + + @sa SetSashPosition() + */ + int GetSashPosition(); + + /** + Gets the split mode. + + @sa SetSplitMode(), SplitVertically(), + SplitHorizontally(). + */ + int GetSplitMode(); + + /** + Returns the left/top or only pane. + */ + wxWindow* GetWindow1(); + + /** + Returns the right/bottom pane. + */ + wxWindow* GetWindow2(); + + /** + Initializes the splitter window to have one pane. The child window is + shown if it is currently hidden. + + @param window + The pane for the unsplit window. + + @remarks This should be called if you wish to initially view only a + single pane in the splitter window. + + @sa SplitVertically(), SplitHorizontally() + */ + void Initialize(wxWindow* window); + + /** + Returns @true if the window is split, @false otherwise. + */ + bool IsSplit(); + + /** + Application-overridable function called when the sash is double-clicked with + the left mouse button. + + @param x + The x position of the mouse cursor. + + @param y + The y position of the mouse cursor. + + @remarks The default implementation of this function calls Unsplit if the + minimum pane size is zero. + + @sa Unsplit() + */ + virtual void OnDoubleClickSash(int x, int y); + + /** + Application-overridable function called when the sash position is changed by + user. It may return @false to prevent the change or @true to allow it. + + @param newSashPosition + The new sash position (always positive or zero) + + @remarks The default implementation of this function verifies that the + sizes of both panes of the splitter are greater than + minimum pane size. + */ + virtual bool OnSashPositionChange(int newSashPosition); + + /** + Application-overridable function called when the window is unsplit, either + programmatically or using the wxSplitterWindow user interface. + + @param removed + The window being removed. + + @remarks The default implementation of this function simply hides + removed. You may wish to delete the window. + */ + virtual void OnUnsplit(wxWindow* removed); + + /** + This function replaces one of the windows managed by the wxSplitterWindow with + another one. It is in general better to use it instead of calling Unsplit() + and then resplitting the window back because it will provoke much less flicker + (if any). It is valid to call this function whether the splitter has two + windows or only one. + + Both parameters should be non-@NULL and @e winOld must specify one of the + windows managed by the splitter. If the parameters are incorrect or the window + couldn't be replaced, @false is returned. Otherwise the function will return + @true, but please notice that it will not delete the replaced window and you + may wish to do it yourself. + + @sa GetMinimumPaneSize() + */ + bool ReplaceWindow(wxWindow * winOld, wxWindow * winNew); + + /** + Sets the minimum pane size. + + @param paneSize + Minimum pane size in pixels. + + @remarks The default minimum pane size is zero, which means that either + pane can be reduced to zero by dragging the sash, + thus removing one of the panes. To prevent this + behaviour (and veto out-of-range sash dragging), set + a minimum size, for example 20 pixels. If the + wxSP_PERMIT_UNSPLIT style is used when a splitter + window is created, the window may be unsplit even if + minimum size is non-zero. + + @sa GetMinimumPaneSize() + */ + void SetMinimumPaneSize(int paneSize); + + /** + Sets the sash gravity. + + @param gravity + The sash gravity. Value between 0.0 and 1.0. + + @sa GetSashGravity() + */ + void SetSashGravity(double gravity); + + /** + Sets the sash position. + + @param position + The sash position in pixels. + + @param redraw + If @true, resizes the panes and redraws the sash and border. + + @remarks Does not currently check for an out-of-range value. + + @sa GetSashPosition() + */ + void SetSashPosition(int position, const bool redraw = @true); + + /** + Sets the sash size. Normally, the sash size is determined according to the + metrics + of each platform, but the application can override this, for example to show + a thin sash that the user is not expected to drag. If @e size is more -1, + the custom sash size will be used. + */ + void SetSashSize(int size); + + /** + Sets the split mode. + + @param mode + Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL. + + @remarks Only sets the internal variable; does not update the display. + + @sa GetSplitMode(), SplitVertically(), + SplitHorizontally(). + */ + void SetSplitMode(int mode); + + /** + Initializes the top and bottom panes of the splitter window. The + child windows are shown if they are currently hidden. + + @param window1 + The top pane. + + @param window2 + The bottom pane. + + @param sashPosition + The initial position of the sash. If this value is + positive, it specifies the size of the upper pane. If it is negative, its + absolute value gives the size of the lower pane. Finally, specify 0 (default) + to choose the default position (half of the total window height). + + @returns @true if successful, @false otherwise (the window was already + split). + + @remarks This should be called if you wish to initially view two panes. + It can also be called at any subsequent time, but the + application should check that the window is not + currently split using IsSplit. + + @sa SplitVertically(), IsSplit(), + Unsplit() + */ + bool SplitHorizontally(wxWindow* window1, wxWindow* window2, + int sashPosition = 0); + + /** + Initializes the left and right panes of the splitter window. The + child windows are shown if they are currently hidden. + + @param window1 + The left pane. + + @param window2 + The right pane. + + @param sashPosition + The initial position of the sash. If this value is + positive, it specifies the size of the left pane. If it is negative, it is + absolute value gives the size of the right pane. Finally, specify 0 (default) + to choose the default position (half of the total window width). + + @returns @true if successful, @false otherwise (the window was already + split). + + @remarks This should be called if you wish to initially view two panes. + It can also be called at any subsequent time, but the + application should check that the window is not + currently split using IsSplit. + + @sa SplitHorizontally(), IsSplit(), + Unsplit(). + */ + bool SplitVertically(wxWindow* window1, wxWindow* window2, + int sashPosition = 0); + + /** + Unsplits the window. + + @param toRemove + The pane to remove, or @NULL to remove the right or bottom pane. + + @returns @true if successful, @false otherwise (the window was not split). + + @remarks This call will not actually delete the pane being removed; it + calls OnUnsplit which can be overridden for the + desired behaviour. By default, the pane being removed + is hidden. + + @sa SplitHorizontally(), SplitVertically(), + IsSplit(), OnUnsplit() + */ + bool Unsplit(wxWindow* toRemove = @NULL); + + /** + Causes any pending sizing of the sash and child panes to take place + immediately. + + Such resizing normally takes place in idle time, in order + to wait for layout to be completed. However, this can cause + unacceptable flicker as the panes are resized after the window has been + shown. To work around this, you can perform window layout (for + example by sending a size event to the parent window), and then + call this function, before showing the top-level window. + */ + void UpdateSize(); +}; + + +/** + @class wxSplitterEvent + @wxheader{splitter.h} + + This class represents the events generated by a splitter control. Also there is + only one event class, the data associated to the different events is not the + same and so not all accessor functions may be called for each event. The + documentation mentions the kind of event(s) for which the given accessor + function makes sense: calling it for other types of events will result + in assert failure (in debug mode) and will return meaningless results. + + @library{wxcore} + @category{events} + + @seealso + wxSplitterWindow, @ref overview_eventhandlingoverview "Event handling overview" +*/ +class wxSplitterEvent : public wxNotifyEvent +{ +public: + /** + Constructor. Used internally by wxWidgets only. + */ + wxSplitterEvent(wxEventType eventType = wxEVT_@NULL, + wxSplitterWindow * splitter = @NULL); + + /** + Returns the new sash position. + + May only be called while processing + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. + */ + int GetSashPosition(); + + /** + Returns a pointer to the window being removed when a splitter window + is unsplit. + + May only be called while processing + wxEVT_COMMAND_SPLITTER_UNSPLIT events. + */ + wxWindow* GetWindowBeingRemoved(); + + /** + Returns the x coordinate of the double-click point. + + May only be called while processing + wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. + */ +#define int GetX() /* implementation is private */ + + /** + Returns the y coordinate of the double-click point. + + May only be called while processing + wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. + */ +#define int GetY() /* implementation is private */ + + /** + In the case of wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events, + sets the new sash position. In the case of + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events, sets the new + tracking bar position so visual feedback during dragging will + represent that change that will actually take place. Set to -1 from + the event handler code to prevent repositioning. + + May only be called while processing + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. + + @param pos + New sash position. + */ + void SetSashPosition(int pos); +}; diff --git a/interface/srchctrl.h b/interface/srchctrl.h new file mode 100644 index 0000000000..6ad9afc3ba --- /dev/null +++ b/interface/srchctrl.h @@ -0,0 +1,137 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: srchctrl.h +// Purpose: documentation for wxSearchCtrl class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSearchCtrl + @wxheader{srchctrl.h} + + A search control is a composite control with a search button, a text + control, and a cancel button. + + @beginStyleTable + @style{wxTE_PROCESS_ENTER}: + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). + @style{wxTE_PROCESS_TAB}: + The control will receive wxEVT_CHAR events for TAB pressed - + normally, TAB is used for passing to the next control in a dialog + instead. For the control created with this style, you can still use + Ctrl-Enter to pass to the next control from the keyboard. + @style{wxTE_NOHIDESEL}: + By default, the Windows text control doesn't show the selection + when it doesn't have focus - use this style to force it to always + show it. It doesn't do anything under other platforms. + @style{wxTE_LEFT}: + The text in the control will be left-justified (default). + @style{wxTE_CENTRE}: + The text in the control will be centered (currently wxMSW and + wxGTK2 only). + @style{wxTE_RIGHT}: + The text in the control will be right-justified (currently wxMSW + and wxGTK2 only). + @style{wxTE_CAPITALIZE}: + On PocketPC and Smartphone, causes the first letter to be + capitalized. + @endStyleTable + + @library{wxcore} + @category{FIXME} + + @seealso + wxTextCtrl::Create, wxValidator +*/ +class wxSearchCtrl : public wxTextCtrl +{ +public: + //@{ + /** + Constructor, creating and showing a text control. + + @param parent + Parent window. Should not be @NULL. + + @param id + Control identifier. A value of -1 denotes a default value. + + @param value + Default text value. + + @param pos + Text control position. + + @param size + Text control size. + + @param style + Window style. See wxSearchCtrl. + + @param validator + Window validator. + + @param name + Window name. + + @sa wxTextCtrl::Create, wxValidator + */ + wxSearchCtrl(); + wxSearchCtrl(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxSearchCtrlNameStr); + //@} + + /** + Destructor, destroying the search control. + */ + ~wxSearchCtrl(); + + /** + Returns a pointer to the search control's menu object or @NULL if there is no + menu attached. + */ + virtual wxMenu* GetMenu(); + + /** + Returns the search button visibility value. + If there is a menu attached, the search button will be visible regardless of + the search + button visibility value. + + This always returns @false in Mac OS X v10.3 + */ + virtual bool IsSearchButtonVisible(); + + /** + Sets the search control's menu object. If there is already a menu associated + with + the search control it is deleted. + + @param menu + Menu to attach to the search control. + */ + virtual void SetMenu(wxMenu* menu); + + /** + Shows or hides the cancel button. + */ + virtual void ShowCancelButton(bool show); + + /** + Sets the search button visibility value on the search control. + If there is a menu attached, the search button will be visible regardless of + the search + button visibility value. + + This has no effect in Mac OS X v10.3 + */ + virtual void ShowSearchButton(bool show); +}; diff --git a/interface/sstream.h b/interface/sstream.h new file mode 100644 index 0000000000..8ff3234cc5 --- /dev/null +++ b/interface/sstream.h @@ -0,0 +1,62 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sstream.h +// Purpose: documentation for wxStringInputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStringInputStream + @wxheader{sstream.h} + + This class implements an input stream which reads data from a string. It + supports seeking. + + @library{wxbase} + @category{streams} +*/ +class wxStringInputStream : public wxInputStream +{ +public: + /** + Creates a new read-only stream using the specified string. Note that the string + is copied by the stream so if the original string is modified after using this + constructor, changes to it are not reflected when reading from stream. + */ + wxStringInputStream(const wxString& s); +}; + + +/** + @class wxStringOutputStream + @wxheader{sstream.h} + + This class implements an output stream which writes data either to a + user-provided or internally allocated string. Note that currently this stream + does not support seeking but can tell its current position. + + @library{wxbase} + @category{streams} +*/ +class wxStringOutputStream : public wxOutputStream +{ +public: + /** + If the provided pointer is non-@NULL, data will be written to it. + Otherwise, an internal string is used for the data written to this stream, use + GetString() to get access to it. + + If @e str is used, data written to the stream is appended to the current + contents of it, i.e. the string is not cleared here. However if it is not + empty, the positions returned by wxOutputStream::TellO will be + offset by the initial string length, i.e. initial stream position will be the + initial length of the string and not 0. + */ + wxStringOutputStream(wxString str = @NULL); + + /** + Returns the string containing all the data written to the stream so far. + */ + const wxString GetString(); +}; diff --git a/interface/stackwalk.h b/interface/stackwalk.h new file mode 100644 index 0000000000..d6015b364a --- /dev/null +++ b/interface/stackwalk.h @@ -0,0 +1,174 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stackwalk.h +// Purpose: documentation for wxStackWalker class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStackWalker + @wxheader{stackwalk.h} + + wxStackWalker allows an application to enumerate, or walk, the stack frames + (the function callstack). + It is mostly useful in only two situations: + inside wxApp::OnFatalException function to + programmatically get the location of the crash and, in debug builds, in + wxApp::OnAssertFailure to report the caller of the failed + assert. + + wxStackWalker works by repeatedly calling + the wxStackWalker::OnStackFrame method for each frame in the + stack, so to use it you must derive your own class from it and override this + method. + + This class will not return anything except raw stack frame addresses if the + debug information is not available. Under Win32 this means that the PDB file + matching the program being executed should be present. Note that if you use + Microsoft Visual C++ compiler, you can create PDB files even for the programs + built in release mode and it doesn't affect the program size (at least if you + don't forget to add @c /opt:ref option which is suppressed by using + @c /debug linker option by default but should be always enabled for + release builds). Under Unix, you need to compile your program with debugging + information (usually using @c -g compiler and linker options) to get the + file and line numbers information, however function names should be available + even without it. Of course, all this is only @true if you build using a recent + enough version of GNU libc which provides the @c backtrace() function + needed to walk the stack. + + @ref overview_debuggingoverview "debugging overview" for how to make it + available. + + @library{wxbase} + @category{FIXME} + + @seealso + wxStackFrame +*/ +class wxStackWalker +{ +public: + /** + Constructor does nothing, use Walk() to walk the + stack. + */ + wxStackWalker(); + + /** + Destructor does nothing neither but should be virtual as this class is used as + a base one. + */ + ~wxStackWalker(); + + /** + This function must be overrided to process the given frame. + */ + void OnStackFrame(const wxStackFrame& frame); + + /** + Enumerate stack frames from the current location, skipping the initial + number of them (this can be useful when Walk() is called from some known + location and you don't want to see the first few frames anyhow; also + notice that Walk() frame itself is not included if skip = 1). + + Up to @e maxDepth frames are walked from the innermost to the outermost one. + */ + void Walk(size_t skip = 1, size_t maxDepth = 200); + + /** + Enumerate stack frames from the location of uncaught exception. + This method can only be called from + wxApp::OnFatalException. + + Up to @e maxDepth frames are walked from the innermost to the outermost one. + */ + void WalkFromException(size_t maxDepth = 200); +}; + + +/** + @class wxStackFrame + @wxheader{stackwalk.h} + + wxStackFrame represents a single stack frame, or a single function in the call + stack, and is used exclusively together with + wxStackWalker, see there for a more detailed + discussion. + + @library{wxbase} + @category{FIXME} + + @seealso + wxStackWalker +*/ +class wxStackFrame +{ +public: + /** + Return the address of this frame. + */ + void* GetAddress(); + + /** + Return the name of the file containing this frame, empty if + unavailable (typically because debug info is missing). + + Use HasSourceLocation() to check whether + the file name is available. + */ + wxString GetFileName(); + + /** + Get the level of this frame (deepest/innermost one is 0). + */ + size_t GetLevel(); + + /** + Return the line number of this frame, 0 if unavailable. + + @sa GetFileName() + */ + size_t GetLine(); + + /** + Get the module this function belongs to (empty if not available). + */ + wxString GetModule(); + + /** + Return the unmangled (if possible) name of the function containing this + frame. + */ + wxString GetName(); + + /** + Return the return address of this frame. + */ + size_t GetOffset(); + + /** + Get the name, type and value (in text form) of the given parameter. + Any pointer may be @NULL if you're not interested in the corresponding + value. + + Return @true if at least some values could be retrieved. + + This function currently is only implemented under Win32 and requires a PDB + file. + */ + bool GetParam(size_t n, wxString * type, wxString * name, + wxString * value); + + /** + Return the number of parameters of this function (may return 0 if we + can't retrieve the parameters info even although the function does have + parameters). + */ + size_t GetParamCount(); + + /** + Return @true if we have the file name and line number for this frame. + */ + bool HasSourceLocation(); +}; diff --git a/interface/statbmp.h b/interface/statbmp.h new file mode 100644 index 0000000000..f212d85ff0 --- /dev/null +++ b/interface/statbmp.h @@ -0,0 +1,110 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: statbmp.h +// Purpose: documentation for wxStaticBitmap class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStaticBitmap + @wxheader{statbmp.h} + + A static bitmap control displays a bitmap. It is meant for display of the + small icons in the dialog boxes and is not meant to be a general purpose image + display control. In particular, under Windows 9x the size of bitmap is limited + to 64*64 pixels and thus you should use your own control if you want to + display larger images portably. + + @library{wxcore} + @category{ctrl} + @appearance{staticbitmap.png} + + @seealso + wxStaticBitmap, wxStaticBox +*/ +class wxStaticBitmap : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a static bitmap control. + + @param parent + Parent window. Should not be @NULL. + + @param id + Control identifier. A value of -1 denotes a default value. + + @param label + Bitmap label. + + @param pos + Window position. + + @param size + Window size. + + @param style + Window style. See wxStaticBitmap. + + @param name + Window name. + + @sa Create() + */ + wxStaticBitmap(); + wxStaticBitmap(wxWindow* parent, wxWindowID id, + const wxBitmap& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticBitmap"); + //@} + + /** + Creation function, for two-step construction. For details see wxStaticBitmap(). + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxBitmap& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticBitmap"); + + /** + Returns the bitmap currently used in the control. Notice that this method can + be called even if SetIcon() had been used. + + @sa SetBitmap() + */ + wxBitmap GetBitmap(); + + /** + Returns the icon currently used in the control. Notice that this method can + only be called if SetIcon() had been used: an icon + can't be retrieved from the control if a bitmap had been set (using + wxStaticBitmap::SetBitmap). + + @sa SetIcon() + */ + wxIcon GetIcon(); + + /** + Sets the bitmap label. + + @param label + The new bitmap. + + @sa GetBitmap() + */ + virtual void SetBitmap(const wxBitmap& label); + + /** + Sets the label to the given icon. + + @param label + The new icon. + */ + virtual void SetIcon(const wxIcon& label); +}; diff --git a/interface/statbox.h b/interface/statbox.h new file mode 100644 index 0000000000..08734706ee --- /dev/null +++ b/interface/statbox.h @@ -0,0 +1,88 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: statbox.h +// Purpose: documentation for wxStaticBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStaticBox + @wxheader{statbox.h} + + A static box is a rectangle drawn around other panel items to denote + a logical grouping of items. + + Please note that a static box should @b not be used as the parent for the + controls it contains, instead they should be siblings of each other. Although + using a static box as a parent might work in some versions of wxWidgets, it + results in a crash under, for example, wxGTK. + + Also, please note that because of this, the order in which you create new + controls is important. Create your wxStaticBox control @b before any + siblings that are to appear inside the wxStaticBox in order to preserve the + correct Z-Order of controls. + + @library{wxcore} + @category{ctrl} + @appearance{staticbox.png} + + @seealso + wxStaticText +*/ +class wxStaticBox : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a static box. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param label + Text to be displayed in the static box, the empty string for no label. + + @param pos + Window position. If wxDefaultPosition is specified then a default position + is chosen. + + @param size + Checkbox size. If the size (-1, -1) is specified then a default size is chosen. + + @param style + Window style. See wxStaticBox. + + @param name + Window name. + + @sa Create() + */ + wxStaticBox(); + wxStaticBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticBox"); + //@} + + /** + Destructor, destroying the group box. + */ + ~wxStaticBox(); + + /** + Creates the static box for two-step construction. See wxStaticBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticBox"); +}; diff --git a/interface/statline.h b/interface/statline.h new file mode 100644 index 0000000000..dc763a4bef --- /dev/null +++ b/interface/statline.h @@ -0,0 +1,87 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: statline.h +// Purpose: documentation for wxStaticLine class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStaticLine + @wxheader{statline.h} + + A static line is just a line which may be used in a dialog to separate the + groups of controls. The line may be only vertical or horizontal. + + @beginStyleTable + @style{wxLI_HORIZONTAL}: + Creates a horizontal line. + @style{wxLI_VERTICAL}: + Creates a vertical line. + @endStyleTable + + @library{wxcore} + @category{FIXME} + + @seealso + wxStaticBox +*/ +class wxStaticLine : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a static line. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. If wxDefaultPosition is specified then a default position + is chosen. + + @param size + Size. Note that either the height or the width (depending on + whether the line if horizontal or vertical) is ignored. + + @param style + Window style (either wxLI_HORIZONTAL or wxLI_VERTICAL). + + @param name + Window name. + + @sa Create() + */ + wxStaticLine(); + wxStaticLine(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxLI_HORIZONTAL, + const wxString& name = "staticLine"); + //@} + + /** + Creates the static line for two-step construction. See wxStaticLine() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticLine"); + + /** + This static function returns the size which will be given to the smaller + dimension of the static line, i.e. its height for a horizontal line or its + width for a vertical one. + */ + int GetDefaultSize(); + + /** + Returns @true if the line is vertical, @false if horizontal. + */ + bool IsVertical(); +}; diff --git a/interface/stattext.h b/interface/stattext.h new file mode 100644 index 0000000000..058335e278 --- /dev/null +++ b/interface/stattext.h @@ -0,0 +1,239 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stattext.h +// Purpose: documentation for wxStaticText class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStaticText + @wxheader{stattext.h} + + A static text control displays one or more lines of read-only text. + + @beginStyleTable + @style{wxALIGN_LEFT}: + Align the text to the left + @style{wxALIGN_RIGHT}: + Align the text to the right + @style{wxALIGN_CENTRE}: + Center the text (horizontally) + @style{wxST_NO_AUTORESIZE}: + By default, the control will adjust its size to exactly fit to the + size of the text when SetLabel is called. If this style flag is + given, the control will not change its size (this style is + especially useful with controls which also have wxALIGN_RIGHT or + CENTER style because otherwise they won't make sense any longer + after a call to SetLabel) + @style{wxST_ELLIPSIZE_START}: + If the text width exceeds the control width, replace the beginning + of the text with an ellipsis + @style{wxST_ELLIPSIZE_MIDDLE}: + Same as above, but replace the text in the middle of the control + with an ellipsis + @style{wxST_ELLIPSIZE_END}: + Same as above, but replace the end of the text with an ellipsis + @style{wxST_MARKUP}: + Support markup in the label; see SetLabel for more information + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{statictext.png} + + @seealso + wxStaticBitmap, wxStaticBox +*/ +class wxStaticText : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a text control. + + @param parent + Parent window. Should not be @NULL. + + @param id + Control identifier. A value of -1 denotes a default value. + + @param label + Text label. + + @param pos + Window position. + + @param size + Window size. + + @param style + Window style. See wxStaticText. + + @param name + Window name. + + @sa Create() + */ + wxStaticText(); + wxStaticText(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticText"); + //@} + + /** + Creation function, for two-step construction. For details see wxStaticText(). + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticText"); + + /** + Returns the contents of the control. + + Note that the returned string contains both the mnemonics (@c characters), + if any, and markup tags, if any. + + Use GetLabelText() if only the + label text is needed. + */ + wxString GetLabel(); + + //@{ + /** + The first form returns the control's label without the mnemonics characters (if + any) + and without the markup (if the control has @c wxST_MARKUP style). + + The second (static) version returns the given @e label string without the + mnemonics + characters (if any) and without the markup. + */ + wxString GetLabelText(); + static wxString GetLabelText(const wxString& label); + //@} + + /** + Sets the static text label and updates the controls size to exactly fit the + label unless the control has wxST_NO_AUTORESIZE flag. + + This function allows to set decorated static label text on platforms which + support it (currently only GTK+ 2). For the other platforms, the markup is + ignored. + + The supported tags are: + + + b + + + bold text + + big + + + bigger text + + i + + + italic text + + s + + + strike-through text + + sub + + + subscript text + + sup + + + superscript text + + small + + + smaller text + + tt + + + monospaced text + + u + + + underlined text + + span + + + generic formatter tag; see Pango Markup for more information. + + Note that the string must be well-formed (e.g. all tags must be correctly + closed) + otherwise it can be not shown correctly or at all. + + Also note that you need to escape the following special characters: + + + @b Special character + + + @b Escape as + + @c + + + @c amp; or as @c + + @c ' + + + @c apos; + + @c " + + + @c quot; + + @c + + + @c lt; + + @c + + + @c gt; + + The non-escaped ampersand @c characters are interpreted as + mnemonics; see wxControl::SetLabel. + Example: + + @param label + The new label to set. It may contain newline characters and the markup tags + described above. + */ + virtual void SetLabel(const wxString& label); + + /** + This functions wraps the controls label so that each of its lines becomes at + most @e width pixels wide if possible (the lines are broken at words + boundaries so it might not be the case if words are too long). If @e width + is negative, no wrapping is done. + + This function is new since wxWidgets version 2.6.2 + */ + void Wrap(int width); +}; diff --git a/interface/statusbr.h b/interface/statusbr.h new file mode 100644 index 0000000000..d2d3ddd9a8 --- /dev/null +++ b/interface/statusbr.h @@ -0,0 +1,223 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: statusbr.h +// Purpose: documentation for wxStatusBar class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStatusBar + @wxheader{statusbr.h} + + A status bar is a narrow window that can be placed along the bottom of a frame + to give + small amounts of status information. It can contain one or more fields, one or + more of which can + be variable length according to the size of the window. + + wxWindow + + wxEvtHandler + + wxObject + + @beginStyleTable + @style{wxST_SIZEGRIP}: + On Windows 95, displays a gripper at right-hand side of the status + bar. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @seealso + wxFrame, @ref overview_samplestatbar "Status bar sample" +*/ +class wxStatusBar : public wxWindow +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent, usually a frame. + + @param id + The window identifier. It may take a value of -1 to indicate a default value. + + @param style + The window style. See wxStatusBar. + + @param name + The name of the window. This parameter is used to associate a name with the + item, + allowing the application user to set Motif resource values for + individual windows. + + @sa Create() + */ + wxStatusBar(); + wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY, + long style = wxST_SIZEGRIP, + const wxString& name = "statusBar"); + //@} + + /** + Destructor. + */ + ~wxStatusBar(); + + /** + Creates the window, for two-step construction. + + See wxStatusBar() for details. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + long style = wxST_SIZEGRIP, + const wxString& name = "statusBar"); + + /** + Returns the size and position of a field's internal bounding rectangle. + + @param i + The field in question. + + @param rect + The rectangle values are placed in this variable. + + @returns @true if the field index is valid, @false otherwise. + + @sa wxRect + */ + virtual bool GetFieldRect(int i, wxRect& rect); + + /** + Returns the number of fields in the status bar. + */ + int GetFieldsCount(); + + /** + Returns the string associated with a status bar field. + + @param i + The number of the status field to retrieve, starting from zero. + + @returns The status field string if the field is valid, otherwise the + empty string. + + @sa SetStatusText() + */ + virtual wxString GetStatusText(int i = 0); + + /** + Sets the field text to the top of the stack, and pops the stack of saved + strings. + + @sa PushStatusText() + */ + void PopStatusText(int field = 0); + + /** + Saves the current field text in a per field stack, and sets the field text + to the string passed as argument. + */ + void PushStatusText(const wxString& string, int field = 0); + + /** + Sets the number of fields, and optionally the field widths. + + @param number + The number of fields. + + @param widths + An array of n integers interpreted in the same way as + in SetStatusWidths + */ + virtual void SetFieldsCount(int number = 1, int* widths = @NULL); + + /** + Sets the minimal possible height for the status bar. The real height may be + bigger than the height specified here depending on the size of the font used by + the status bar. + */ + void SetMinHeight(int height); + + /** + Sets the styles of the fields in the status line which can make fields appear + flat + or raised instead of the standard sunken 3D border. + + @param n + The number of fields in the status bar. Must be equal to the + number passed to SetFieldsCount the last + time it was called. + + @param styles + Contains an array of n integers with the styles for each field. There + are three possible styles: + + + wxSB_NORMAL + + + (default) The field appears sunken with a standard 3D border. + + wxSB_FLAT + + + No border is painted around the field so that it appears flat. + + wxSB_RAISED + + + A raised 3D border is painted around the field. + */ + virtual void SetStatusStyles(int n, int * styles); + + /** + Sets the text for one field. + + @param text + The text to be set. Use an empty string ("") to clear the field. + + @param i + The field to set, starting from zero. + + @sa GetStatusText(), wxFrame::SetStatusText + */ + virtual void SetStatusText(const wxString& text, int i = 0); + + /** + Sets the widths of the fields in the status line. There are two types of + fields: fixed widths one and variable width fields. For the fixed width fields + you should specify their (constant) width in pixels. For the variable width + fields, specify a negative number which indicates how the field should expand: + the space left for all variable width fields is divided between them according + to the absolute value of this number. A variable width field with width of -2 + gets twice as much of it as a field with width -1 and so on. + + For example, to create one fixed width field of width 100 in the right part of + the status bar and two more fields which get 66% and 33% of the remaining + space correspondingly, you should use an array containing -2, -1 and 100. + + @param n + The number of fields in the status bar. Must be equal to the + number passed to SetFieldsCount the last + time it was called. + + @param widths + Contains an array of n integers, each of which is + either an absolute status field width in pixels if positive or indicates a + variable width field if negative. + + @remarks The widths of the variable fields are calculated from the total + width of all fields, minus the sum of widths of the + non-variable fields, divided by the number of + variable fields. + + @sa SetFieldsCount(), wxFrame::SetStatusWidths + */ + virtual void SetStatusWidths(int n, int * widths); +}; diff --git a/interface/stc/stc.h b/interface/stc/stc.h new file mode 100644 index 0000000000..f64c9b80e9 --- /dev/null +++ b/interface/stc/stc.h @@ -0,0 +1,2746 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stc/stc.h +// Purpose: documentation for wxStyledTextEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStyledTextEvent + @headerfile stc.h wx/stc/stc.h + + The type of events sent from wxStyledTextCtrl. + + TODO + + @library{wxbase} + @category{FIXME} +*/ +class wxStyledTextEvent : public wxCommandEvent +{ +public: + //@{ + /** + + */ + wxStyledTextEvent(wxEventType commandType = 0, int id = 0); + wxStyledTextEvent(const wxStyledTextEvent& event); + //@} + + /** + + */ + wxEvent* Clone(); + + /** + + */ + bool GetAlt(); + + /** + + */ + bool GetControl(); + + /** + + */ + bool GetDragAllowMove(); + + /** + + */ + wxDragResult GetDragResult(); + + /** + + */ + wxString GetDragText(); + + /** + + */ + int GetFoldLevelNow(); + + /** + + */ + int GetFoldLevelPrev(); + + /** + + */ + int GetKey(); + + /** + + */ + int GetLParam(); + + /** + + */ + int GetLength(); + + /** + + */ + int GetLine(); + + /** + + */ + int GetLinesAdded(); + + /** + + */ + int GetListType(); + + /** + + */ + int GetMargin(); + + /** + + */ + int GetMessage(); + + /** + + */ + int GetModificationType(); + + /** + + */ + int GetModifiers(); + + /** + + */ + int GetPosition(); + + /** + + */ + bool GetShift(); + + /** + + */ + wxString GetText(); + + /** + + */ + int GetWParam(); + + /** + + */ +#define int GetX() /* implementation is private */ + + /** + + */ +#define int GetY() /* implementation is private */ + + /** + + */ + void SetDragAllowMove(bool val); + + /** + + */ + void SetDragResult(wxDragResult val); + + /** + + */ + void SetDragText(const wxString& val); + + /** + + */ + void SetFoldLevelNow(int val); + + /** + + */ + void SetFoldLevelPrev(int val); + + /** + + */ + void SetKey(int k); + + /** + + */ + void SetLParam(int val); + + /** + + */ + void SetLength(int len); + + /** + + */ + void SetLine(int val); + + /** + + */ + void SetLinesAdded(int num); + + /** + + */ + void SetListType(int val); + + /** + + */ + void SetMargin(int val); + + /** + + */ + void SetMessage(int val); + + /** + + */ + void SetModificationType(int t); + + /** + + */ + void SetModifiers(int m); + + /** + + */ + void SetPosition(int pos); + + /** + + */ + void SetText(const wxString& t); + + /** + + */ + void SetWParam(int val); + + /** + + */ +#define void SetX(int val) /* implementation is private */ + + /** + + */ +#define void SetY(int val) /* implementation is private */ +}; + + +/** + @class wxStyledTextCtrl + @headerfile stc.h wx/stc/stc.h + + A wxWidgets implementation of the Scintilla source code editing component. + + As well as features found in standard text editing components, Scintilla + includes + features especially useful when editing and debugging source code. These + include + support for syntax styling, error indicators, code completion and call tips. + The + selection margin can contain markers like those used in debuggers to indicate + breakpoints and the current line. Styling choices are more open than with many + editors, allowing the use of proportional fonts, bold and italics, multiple + foreground and background colours and multiple fonts. + + wxStyledTextCtrl is a 1 to 1 mapping of "raw" scintilla interface, whose + documentation + can be found in the Scintilla website. + + @library{wxbase} + @category{stc} + + @seealso + wxStyledTextEvent +*/ +class wxStyledTextCtrl : public wxControl +{ +public: + /** + Ctor. + */ + wxStyledTextCtrl::wxStyledTextCtrl(wxWindow * parent, + wxWindowID id = wxID_ANY, + const wxPoint pos = wxDefaultPosition, + const wxSize size = wxDefaultSize, + long style = 0, + const wxString name = "stcwindow"); + + /** + Extend life of document. + */ + void AddRefDocument(void* docPointer); + + /** + Add array of cells to document. + */ + void AddStyledText(const wxMemoryBuffer& data); + + /** + BEGIN generated section. The following code is automatically generated + by gen_iface.py. Do not edit this file. Edit stc.h.in instead + and regenerate + Add text to the document at current position. + */ + void AddText(const wxString& text); + + /** + The following methods are nearly equivallent to their similarly named + cousins above. The difference is that these methods bypass wxString + and always use a char* even if used in a unicode build of wxWidgets. + In that case the character data will be utf-8 encoded since that is + what is used internally by Scintilla in unicode builds. + Add text to the document at current position. + */ + void AddTextRaw(const char* text); + + /** + Enlarge the document to a particular size of text bytes. + */ + void Allocate(int bytes); + + /** + Append a string to the end of the document without changing the selection. + */ + void AppendText(const wxString& text); + + /** + Append a string to the end of the document without changing the selection. + */ + void AppendTextRaw(const char* text); + + /** + Is there an auto-completion list visible? + */ + bool AutoCompActive(); + + /** + Remove the auto-completion list from the screen. + */ + void AutoCompCancel(); + + /** + User has selected an item so remove the list and insert the selection. + */ + void AutoCompComplete(); + + /** + Retrieve whether or not autocompletion is hidden automatically when nothing + matches. + */ + bool AutoCompGetAutoHide(); + + /** + Retrieve whether auto-completion cancelled by backspacing before start. + */ + bool AutoCompGetCancelAtStart(); + + /** + Retrieve whether a single item auto-completion list automatically choose the + item. + */ + bool AutoCompGetChooseSingle(); + + /** + Get currently selected item position in the auto-completion list + */ + int AutoCompGetCurrent(); + + /** + Retrieve whether or not autocompletion deletes any word characters + after the inserted text upon completion. + */ + bool AutoCompGetDropRestOfWord(); + + /** + Retrieve state of ignore case flag. + */ + bool AutoCompGetIgnoreCase(); + + /** + Set the maximum height, in rows, of auto-completion and user lists. + */ + int AutoCompGetMaxHeight(); + + /** + Get the maximum width, in characters, of auto-completion and user lists. + */ + int AutoCompGetMaxWidth(); + + /** + Retrieve the auto-completion list separator character. + */ + int AutoCompGetSeparator(); + + /** + Retrieve the auto-completion list type-separator character. + */ + int AutoCompGetTypeSeparator(); + + /** + Retrieve the position of the caret when the auto-completion list was displayed. + */ + int AutoCompPosStart(); + + /** + Select the item in the auto-completion list that starts with a string. + */ + void AutoCompSelect(const wxString& text); + + /** + Set whether or not autocompletion is hidden automatically when nothing matches. + */ + void AutoCompSetAutoHide(bool autoHide); + + /** + Should the auto-completion list be cancelled if the user backspaces to a + position before where the box was created. + */ + void AutoCompSetCancelAtStart(bool cancel); + + /** + Should a single item auto-completion list automatically choose the item. + */ + void AutoCompSetChooseSingle(bool chooseSingle); + + /** + Set whether or not autocompletion deletes any word characters + after the inserted text upon completion. + */ + void AutoCompSetDropRestOfWord(bool dropRestOfWord); + + /** + Define a set of characters that when typed will cause the autocompletion to + choose the selected item. + */ + void AutoCompSetFillUps(const wxString& characterSet); + + /** + Set whether case is significant when performing auto-completion searches. + */ + void AutoCompSetIgnoreCase(bool ignoreCase); + + /** + Set the maximum height, in rows, of auto-completion and user lists. + The default is 5 rows. + */ + void AutoCompSetMaxHeight(int rowCount); + + /** + Set the maximum width, in characters, of auto-completion and user lists. + Set to 0 to autosize to fit longest item, which is the default. + */ + void AutoCompSetMaxWidth(int characterCount); + + /** + Change the separator character in the string setting up an auto-completion list. + Default is space but can be changed if items contain space. + */ + void AutoCompSetSeparator(int separatorCharacter); + + /** + Change the type-separator character in the string setting up an auto-completion + list. + Default is '?' but can be changed if items contain '?'. + */ + void AutoCompSetTypeSeparator(int separatorCharacter); + + /** + Display a auto-completion list. + The lenEntered parameter indicates how many characters before + the caret should be used to provide context. + */ + void AutoCompShow(int lenEntered, const wxString& itemList); + + /** + Define a set of character that when typed cancel the auto-completion list. + */ + void AutoCompStops(const wxString& characterSet); + + /** + Dedent the selected lines. + */ + void BackTab(); + + /** + Start a sequence of actions that is undone and redone as a unit. + May be nested. + */ + void BeginUndoAction(); + + /** + Highlight the character at a position indicating there is no matching brace. + */ + void BraceBadLight(int pos); + + /** + Highlight the characters at two positions. + */ + void BraceHighlight(int pos1, int pos2); + + /** + Find the position of a matching brace or INVALID_POSITION if no match. + */ + int BraceMatch(int pos); + + /** + Is there an active call tip? + */ + bool CallTipActive(); + + /** + Remove the call tip from the screen. + */ + void CallTipCancel(); + + /** + Retrieve the position where the caret was before displaying the call tip. + */ + int CallTipPosAtStart(); + + /** + Set the background colour for the call tip. + */ + void CallTipSetBackground(const wxColour& back); + + /** + Set the foreground colour for the call tip. + */ + void CallTipSetForeground(const wxColour& fore); + + /** + Set the foreground colour for the highlighted part of the call tip. + */ + void CallTipSetForegroundHighlight(const wxColour& fore); + + /** + Highlight a segment of the definition. + */ + void CallTipSetHighlight(int start, int end); + + /** + Show a call tip containing a definition near position pos. + */ + void CallTipShow(int pos, const wxString& definition); + + /** + Enable use of STYLE_CALLTIP and set call tip tab size in pixels. + */ + void CallTipUseStyle(int tabSize); + + /** + Will a paste succeed? + */ + bool CanPaste(); + + /** + Are there any redoable actions in the undo history? + */ + bool CanRedo(); + + /** + Are there any undoable actions in the undo history? + */ + bool CanUndo(); + + /** + Cancel any modes such as call tip or auto-completion list display. + */ + void Cancel(); + + /** + Move caret left one character. + */ + void CharLeft(); + + /** + Move caret left one character extending selection to new caret position. + */ + void CharLeftExtend(); + + /** + Move caret left one character, extending rectangular selection to new caret + position. + */ + void CharLeftRectExtend(); + + /** + Move caret right one character. + */ + void CharRight(); + + /** + Move caret right one character extending selection to new caret position. + */ + void CharRightExtend(); + + /** + Move caret right one character, extending rectangular selection to new caret + position. + */ + void CharRightRectExtend(); + + /** + Set the last x chosen value to be the caret x position. + */ + void ChooseCaretX(); + + /** + Clear the selection. + */ + void Clear(); + + /** + Delete all text in the document. + */ + void ClearAll(); + + /** + Set all style bytes to 0, remove all folding information. + */ + void ClearDocumentStyle(); + + /** + Clear all the registered images. + */ + void ClearRegisteredImages(); + + /** + When key+modifier combination km is pressed perform msg. + */ + void CmdKeyAssign(int key, int modifiers, int cmd); + + /** + When key+modifier combination km is pressed do nothing. + */ + void CmdKeyClear(int key, int modifiers); + + /** + Drop all key mappings. + */ + void CmdKeyClearAll(); + + /** + Perform one of the operations defined by the wxSTC_CMD_* constants. + */ + void CmdKeyExecute(int cmd); + + /** + Colourise a segment of the document using the current lexing language. + */ + void Colourise(int start, int end); + + /** + Convert all line endings in the document to one mode. + */ + void ConvertEOLs(int eolMode); + + /** + Copy the selection to the clipboard. + */ + void Copy(); + + /** + Copy a range of text to the clipboard. Positions are clipped into the document. + */ + void CopyRange(int start, int end); + + /** + Copy argument text to the clipboard. + */ + void CopyText(int length, const wxString& text); + + /** + + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxSTCNameStr); + + /** + Create a new document object. + Starts with reference count of 1 and not selected into editor. + */ + void* CreateDocument(); + + /** + Cut the selection to the clipboard. + */ +#define void Cut() /* implementation is private */ + + /** + Delete back from the current position to the start of the line. + */ + void DelLineLeft(); + + /** + Delete forwards from the current position to the end of the line. + */ + void DelLineRight(); + + /** + Delete the word to the left of the caret. + */ + void DelWordLeft(); + + /** + Delete the word to the right of the caret. + */ + void DelWordRight(); + + /** + Delete the selection or if no selection, the character before the caret. + */ + void DeleteBack(); + + /** + Delete the selection or if no selection, the character before the caret. + Will not delete the character before at the start of a line. + */ + void DeleteBackNotLine(); + + /** + Allow for simulating a DnD DragOver + */ + wxDragResult DoDragOver(wxCoord x, wxCoord y, wxDragResult def); + + /** + Allow for simulating a DnD DropText + */ + bool DoDropText(long x, long y, const wxString& data); + + /** + Find the document line of a display line taking hidden lines into account. + */ + int DocLineFromVisible(int lineDisplay); + + /** + Move caret to last position in document. + */ + void DocumentEnd(); + + /** + Move caret to last position in document extending selection to new caret + position. + */ + void DocumentEndExtend(); + + /** + Move caret to first position in document. + */ + void DocumentStart(); + + /** + Move caret to first position in document extending selection to new caret + position. + */ + void DocumentStartExtend(); + + /** + Switch from insert to overtype mode or the reverse. + */ + void EditToggleOvertype(); + + /** + Delete the undo history. + */ + void EmptyUndoBuffer(); + + /** + End a sequence of actions that is undone and redone as a unit. + */ + void EndUndoAction(); + + /** + Ensure the caret is visible. + */ + void EnsureCaretVisible(); + + /** + Ensure a particular line is visible by expanding any header line hiding it. + */ + void EnsureVisible(int line); + + /** + Ensure a particular line is visible by expanding any header line hiding it. + Use the currently set visibility policy to determine which range to display. + */ + void EnsureVisibleEnforcePolicy(int line); + + /** + Find the position of a column on a line taking into account tabs and + multi-byte characters. If beyond end of line, return line end position. + */ + int FindColumn(int line, int column); + + /** + Find some text in the document. + */ + int FindText(int minPos, int maxPos, const wxString& text, + int flags = 0); + + /** + Insert a Form Feed character. + */ + void FormFeed(); + + /** + On Windows, will draw the document into a display context such as a printer. + */ + int FormatRange(bool doDraw, int startPos, int endPos, + wxDC* draw, wxDC* target, + wxRect renderRect, + wxRect pageRect); + + /** + Returns the position of the opposite end of the selection to the caret. + */ + int GetAnchor(); + + /** + Does a backspace pressed when caret is within indentation unindent? + */ + bool GetBackSpaceUnIndents(); + + /** + Is drawing done first into a buffer or direct to the screen? + */ + bool GetBufferedDraw(); + + /** + Get the foreground colour of the caret. + */ + wxColour GetCaretForeground(); + + /** + Get the background alpha of the caret line. + */ + int GetCaretLineBackAlpha(); + + /** + Get the colour of the background of the line containing the caret. + */ + wxColour GetCaretLineBackground(); + + /** + Is the background of the line containing the caret in a different colour? + */ + bool GetCaretLineVisible(); + + /** + Get the time in milliseconds that the caret is on and off. + */ + int GetCaretPeriod(); + + /** + Can the caret preferred x position only be changed by explicit movement + commands? + */ + bool GetCaretSticky(); + + /** + Returns the width of the insert mode caret. + */ + int GetCaretWidth(); + + /** + Returns the character byte at the position. + */ + int GetCharAt(int pos); + + /** + Get the code page used to interpret the bytes of the document as characters. + */ + int GetCodePage(); + + /** + Retrieve the column number of a position, taking tab width into account. + */ + int GetColumn(int pos); + + /** + Get the way control characters are displayed. + */ + int GetControlCharSymbol(); + + /** + + */ + wxString GetCurLine(int* OUTPUT); + + /** + + */ + wxCharBuffer GetCurLineRaw(int* OUTPUT); + + /** + END of generated section + + Others... + Returns the line number of the line with the caret. + */ + int GetCurrentLine(); + + /** + Returns the position of the caret. + */ + int GetCurrentPos(); + + /** + Retrieve a pointer to the document object. + */ + void* GetDocPointer(); + + /** + Retrieve the current end of line mode - one of CRLF, CR, or LF. + */ + int GetEOLMode(); + + /** + Retrieve the colour used in edge indication. + */ + wxColour GetEdgeColour(); + + /** + Retrieve the column number which text should be kept within. + */ + int GetEdgeColumn(); + + /** + Retrieve the edge highlight mode. + */ + int GetEdgeMode(); + + /** + Retrieve whether the maximum scroll position has the last + line at the bottom of the view. + */ + bool GetEndAtLastLine(); + + /** + Retrieve the position of the last correctly styled character. + */ + int GetEndStyled(); + + /** + Retrieve the display line at the top of the display. + */ + int GetFirstVisibleLine(); + + /** + Is a header line expanded? + */ + bool GetFoldExpanded(int line); + + /** + Retrieve the fold level of a line. + */ + int GetFoldLevel(int line); + + /** + Find the parent line of a child line. + */ + int GetFoldParent(int line); + + /** + Get the highlighted indentation guide column. + */ + int GetHighlightGuide(); + + /** + Retrieve indentation size. + */ + int GetIndent(); + + /** + Are the indentation guides visible? + */ + bool GetIndentationGuides(); + + /** + Find the last child line of a header line. + */ + int GetLastChild(int line, int level); + + /** + Can be used to prevent the EVT_CHAR handler from adding the char + */ + bool GetLastKeydownProcessed(); + + /** + Retrieve the degree of caching of layout information. + */ + int GetLayoutCache(); + + /** + Returns the number of characters in the document. + */ + int GetLength(); + + /** + Retrieve the lexing language of the document. + */ + int GetLexer(); + + /** + Retrieve the contents of a line. + */ + wxString GetLine(int line); + + /** + Returns the number of lines in the document. There is always at least one. + */ + int GetLineCount(); + + /** + Get the position after the last visible characters on a line. + */ + int GetLineEndPosition(int line); + + /** + Retrieve the position before the first non indentation character on a line. + */ + int GetLineIndentPosition(int line); + + /** + Retrieve the number of columns that a line is indented. + */ + int GetLineIndentation(int line); + + /** + Retrieve the contents of a line. + */ + wxCharBuffer GetLineRaw(int line); + + /** + Retrieve the position of the end of the selection at the given line + (INVALID_POSITION if no selection on this line). + */ + int GetLineSelEndPosition(int line); + + /** + Retrieve the position of the start of the selection at the given line + (INVALID_POSITION if no selection on this line). + */ + int GetLineSelStartPosition(int line); + + /** + Retrieve the extra styling information for a line. + */ + int GetLineState(int line); + + /** + Is a line visible? + */ + bool GetLineVisible(int line); + + /** + Returns the size in pixels of the left margin. + */ + int GetMarginLeft(); + + /** + Retrieve the marker mask of a margin. + */ + int GetMarginMask(int margin); + + /** + Returns the size in pixels of the right margin. + */ + int GetMarginRight(); + + /** + Retrieve the mouse click sensitivity of a margin. + */ + bool GetMarginSensitive(int margin); + + /** + Retrieve the type of a margin. + */ + int GetMarginType(int margin); + + /** + Retrieve the width of a margin in pixels. + */ + int GetMarginWidth(int margin); + + /** + Retrieve the last line number that has line state. + */ + int GetMaxLineState(); + + /** + Get which document modification events are sent to the container. + */ + int GetModEventMask(); + + /** + Is the document different from when it was last saved? + */ + bool GetModify(); + + /** + Get whether mouse gets captured. + */ + bool GetMouseDownCaptures(); + + /** + Retrieve the time the mouse must sit still to generate a mouse dwell event. + */ + int GetMouseDwellTime(); + + /** + Returns @true if overtype mode is active otherwise @false is returned. + */ + bool GetOvertype(); + + /** + Get convert-on-paste setting + */ + bool GetPasteConvertEndings(); + + /** + Returns the print colour mode. + */ + int GetPrintColourMode(); + + /** + Returns the print magnification. + */ + int GetPrintMagnification(); + + /** + Is printing line wrapped? + */ + int GetPrintWrapMode(); + + /** + Retrieve a 'property' value previously set with SetProperty. + */ + wxString GetProperty(const wxString& key); + + /** + Retrieve a 'property' value previously set with SetProperty, + with '$()' variable replacement on returned buffer. + */ + wxString GetPropertyExpanded(const wxString& key); + + /** + Retrieve a 'property' value previously set with SetProperty, + interpreted as an int AFTER any '$()' variable replacement. + */ + int GetPropertyInt(const wxString& key); + + /** + In read-only mode? + */ + bool GetReadOnly(); + + /** + Get cursor type. + */ + int GetSTCCursor(); + + /** + Get internal focus flag. + */ + bool GetSTCFocus(); + + /** + Retrieve the document width assumed for scrolling. + */ + int GetScrollWidth(); + + /** + Get the search flags used by SearchInTarget. + */ + int GetSearchFlags(); + + /** + Get the alpha of the selection. + */ + int GetSelAlpha(); + + /** + Retrieve the selected text. + */ + wxString GetSelectedText(); + + /** + Retrieve the selected text. + */ + wxCharBuffer GetSelectedTextRaw(); + + /** + + */ + void GetSelection(int* OUTPUT, int* OUTPUT); + + /** + Returns the position at the end of the selection. + */ + int GetSelectionEnd(); + + /** + Get the mode of the current selection. + */ + int GetSelectionMode(); + + /** + Returns the position at the start of the selection. + */ + int GetSelectionStart(); + + /** + Get error status. + */ + int GetStatus(); + + /** + Returns the style byte at the position. + */ + int GetStyleAt(int pos); + + /** + Retrieve number of bits in style bytes used to hold the lexical state. + */ + int GetStyleBits(); + + /** + Retrieve the number of bits the current lexer needs for styling. + */ + int GetStyleBitsNeeded(); + + /** + Retrieve a buffer of cells. + */ + wxMemoryBuffer GetStyledText(int startPos, int endPos); + + /** + Does a tab pressed when caret is within indentation indent? + */ + bool GetTabIndents(); + + /** + Retrieve the visible size of a tab. + */ + int GetTabWidth(); + + /** + Get the position that ends the target. + */ + int GetTargetEnd(); + + /** + Get the position that starts the target. + */ + int GetTargetStart(); + + /** + Retrieve all the text in the document. + */ + wxString GetText(); + + /** + Retrieve the number of characters in the document. + */ + int GetTextLength(); + + /** + Retrieve a range of text. + */ + wxString GetTextRange(int startPos, int endPos); + + /** + Retrieve a range of text. + */ + wxCharBuffer GetTextRangeRaw(int startPos, int endPos); + + /** + Retrieve all the text in the document. + */ + wxCharBuffer GetTextRaw(); + + /** + Is drawing done in two phases with backgrounds drawn before foregrounds? + */ + bool GetTwoPhaseDraw(); + + /** + Is undo history being collected? + */ + bool GetUndoCollection(); + + /** + Returns the current UseAntiAliasing setting. + */ + bool GetUseAntiAliasing(); + + /** + Is the horizontal scroll bar visible? + */ + bool GetUseHorizontalScrollBar(); + + /** + Retrieve whether tabs will be used in indentation. + */ + bool GetUseTabs(); + + /** + Is the vertical scroll bar visible? + */ + bool GetUseVerticalScrollBar(); + + /** + Are the end of line characters visible? + */ + bool GetViewEOL(); + + /** + Are white space characters currently visible? + Returns one of SCWS_* constants. + */ + int GetViewWhiteSpace(); + + /** + Retrieve whether text is word wrapped. + */ + int GetWrapMode(); + + /** + Retrive the start indent for wrapped lines. + */ + int GetWrapStartIndent(); + + /** + Retrive the display mode of visual flags for wrapped lines. + */ + int GetWrapVisualFlags(); + + /** + Retrive the location of visual flags for wrapped lines. + */ + int GetWrapVisualFlagsLocation(); + + /** + + */ + int GetXOffset(); + + /** + Retrieve the zoom level. + */ + int GetZoom(); + + /** + Set caret to start of a line and ensure it is visible. + */ + void GotoLine(int line); + + /** + Set caret to a position and ensure it is visible. + */ + void GotoPos(int pos); + + /** + Make a range of lines invisible. + */ + void HideLines(int lineStart, int lineEnd); + + /** + Draw the selection in normal style or with selection highlighted. + */ + void HideSelection(bool normal); + + /** + Move caret to first position on line. + */ + void Home(); + + /** + Move caret to first position on display line. + */ + void HomeDisplay(); + + /** + Move caret to first position on display line extending selection to + new caret position. + */ + void HomeDisplayExtend(); + + /** + Move caret to first position on line extending selection to new caret position. + */ + void HomeExtend(); + + /** + Move caret to first position on line, extending rectangular selection to new + caret position. + */ + void HomeRectExtend(); + + /** + These are like their namesakes Home(Extend)?, LineEnd(Extend)?, VCHome(Extend)? + except they behave differently when word-wrap is enabled: + They go first to the start / end of the display line, like (Home|LineEnd)Display + The difference is that, the cursor is already at the point, it goes on to the + start + or end of the document line, as appropriate for (Home|LineEnd|VCHome)(Extend)?. + */ + void HomeWrap(); + + /** + + */ + void HomeWrapExtend(); + + /** + Retrieve the foreground colour of an indicator. + */ + wxColour IndicatorGetForeground(int indic); + + /** + Retrieve the style of an indicator. + */ + int IndicatorGetStyle(int indic); + + /** + Set the foreground colour of an indicator. + */ + void IndicatorSetForeground(int indic, const wxColour& fore); + + /** + Set an indicator to plain, squiggle or TT. + */ + void IndicatorSetStyle(int indic, int style); + + /** + Insert string at a position. + */ + void InsertText(int pos, const wxString& text); + + /** + Insert string at a position. + */ + void InsertTextRaw(int pos, const char* text); + + /** + Copy the line containing the caret. + */ + void LineCopy(); + + /** + Cut the line containing the caret. + */ + void LineCut(); + + /** + Delete the line containing the caret. + */ + void LineDelete(); + + /** + Move caret down one line. + */ + void LineDown(); + + /** + Move caret down one line extending selection to new caret position. + */ + void LineDownExtend(); + + /** + Move caret down one line, extending rectangular selection to new caret position. + */ + void LineDownRectExtend(); + + /** + Duplicate the current line. + */ + void LineDuplicate(); + + /** + Move caret to last position on line. + */ + void LineEnd(); + + /** + Move caret to last position on display line. + */ + void LineEndDisplay(); + + /** + Move caret to last position on display line extending selection to new + caret position. + */ + void LineEndDisplayExtend(); + + /** + Move caret to last position on line extending selection to new caret position. + */ + void LineEndExtend(); + + /** + Move caret to last position on line, extending rectangular selection to new + caret position. + */ + void LineEndRectExtend(); + + /** + + */ + void LineEndWrap(); + + /** + + */ + void LineEndWrapExtend(); + + /** + Retrieve the line containing a position. + */ + int LineFromPosition(int pos); + + /** + How many characters are on a line, not including end of line characters? + */ + int LineLength(int line); + + /** + Scroll horizontally and vertically. + */ + void LineScroll(int columns, int lines); + + /** + Scroll the document down, keeping the caret visible. + */ + void LineScrollDown(); + + /** + Scroll the document up, keeping the caret visible. + */ + void LineScrollUp(); + + /** + Switch the current line with the previous. + */ + void LineTranspose(); + + /** + Move caret up one line. + */ + void LineUp(); + + /** + Move caret up one line extending selection to new caret position. + */ + void LineUpExtend(); + + /** + Move caret up one line, extending rectangular selection to new caret position. + */ + void LineUpRectExtend(); + + /** + Join the lines in the target. + */ + void LinesJoin(); + + /** + Retrieves the number of lines completely visible. + */ + int LinesOnScreen(); + + /** + Split the lines in the target into lines that are less wide than pixelWidth + where possible. + */ + void LinesSplit(int pixelWidth); + + /** + Load the contents of filename into the editor + */ + bool LoadFile(const wxString& filename); + + /** + Transform the selection to lower case. + */ + void LowerCase(); + + /** + Add a marker to a line, returning an ID which can be used to find or delete the + marker. + */ + int MarkerAdd(int line, int markerNumber); + + /** + Add a set of markers to a line. + */ + void MarkerAddSet(int line, int set); + + /** + Set the symbol used for a particular marker number, + and optionally the fore and background colours. + */ + void MarkerDefine(int markerNumber, int markerSymbol, + const wxColour& foreground = wxNullColour, + const wxColour& background = wxNullColour); + + /** + Define a marker from a bitmap + */ + void MarkerDefineBitmap(int markerNumber, const wxBitmap& bmp); + + /** + Delete a marker from a line. + */ + void MarkerDelete(int line, int markerNumber); + + /** + Delete all markers with a particular number from all lines. + */ + void MarkerDeleteAll(int markerNumber); + + /** + Delete a marker. + */ + void MarkerDeleteHandle(int handle); + + /** + Get a bit mask of all the markers set on a line. + */ + int MarkerGet(int line); + + /** + Retrieve the line number at which a particular marker is located. + */ + int MarkerLineFromHandle(int handle); + + /** + Find the next line after lineStart that includes a marker in mask. + */ + int MarkerNext(int lineStart, int markerMask); + + /** + Find the previous line before lineStart that includes a marker in mask. + */ + int MarkerPrevious(int lineStart, int markerMask); + + /** + Set the alpha used for a marker that is drawn in the text area, not the margin. + */ + void MarkerSetAlpha(int markerNumber, int alpha); + + /** + Set the background colour used for a particular marker number. + */ + void MarkerSetBackground(int markerNumber, const wxColour& back); + + /** + Set the foreground colour used for a particular marker number. + */ + void MarkerSetForeground(int markerNumber, const wxColour& fore); + + /** + Move the caret inside current view if it's not there already. + */ + void MoveCaretInsideView(); + + /** + Insert a new line, may use a CRLF, CR or LF depending on EOL mode. + */ + void NewLine(); + + /** + Move caret one page down. + */ + void PageDown(); + + /** + Move caret one page down extending selection to new caret position. + */ + void PageDownExtend(); + + /** + Move caret one page down, extending rectangular selection to new caret position. + */ + void PageDownRectExtend(); + + /** + Move caret one page up. + */ + void PageUp(); + + /** + Move caret one page up extending selection to new caret position. + */ + void PageUpExtend(); + + /** + Move caret one page up, extending rectangular selection to new caret position. + */ + void PageUpRectExtend(); + + /** + Move caret between paragraphs (delimited by empty lines). + */ + void ParaDown(); + + /** + + */ + void ParaDownExtend(); + + /** + + */ + void ParaUp(); + + /** + + */ + void ParaUpExtend(); + + /** + Paste the contents of the clipboard into the document replacing the selection. + */ + void Paste(); + + /** + Retrieve the point in the window where a position is displayed. + */ + wxPoint PointFromPosition(int pos); + + /** + Given a valid document position, return the next position taking code + page into account. Maximum value returned is the last position in the document. + */ + int PositionAfter(int pos); + + /** + Given a valid document position, return the previous position taking code + page into account. Returns 0 if passed 0. + */ + int PositionBefore(int pos); + + /** + Retrieve the position at the start of a line. + */ + int PositionFromLine(int line); + + /** + Find the position from a point within the window. + */ + int PositionFromPoint(wxPoint pt); + + /** + Find the position from a point within the window but return + INVALID_POSITION if not close to text. + */ + int PositionFromPointClose(int x, int y); + + /** + Redoes the next action on the undo history. + */ + void Redo(); + + /** + Register an image for use in autocompletion lists. + */ + void RegisterImage(int type, const wxBitmap& bmp); + + /** + Release a reference to the document, deleting document if it fades to black. + */ + void ReleaseDocument(void* docPointer); + + /** + Replace the selected text with the argument text. + */ + void ReplaceSelection(const wxString& text); + + /** + Replace the target text with the argument text. + Text is counted so it can contain NULs. + Returns the length of the replacement text. + */ + int ReplaceTarget(const wxString& text); + + /** + Replace the target text with the argument text after + d processing. + Text is counted so it can contain NULs. + Looks for + d where d is between 1 and 9 and replaces these with the strings + matched in the last search operation which were surrounded by + ( and + ). + Returns the length of the replacement text including any change + caused by processing the + d patterns. + */ + int ReplaceTargetRE(const wxString& text); + + /** + Write the contents of the editor to filename + */ + bool SaveFile(const wxString& filename); + + /** + Scroll enough to make the given column visible + */ + void ScrollToColumn(int column); + + /** + Scroll enough to make the given line visible + */ + void ScrollToLine(int line); + + /** + Sets the current caret position to be the search anchor. + */ + void SearchAnchor(); + + /** + Search for a counted string in the target and set the target to the found + range. Text is counted so it can contain NULs. + Returns length of range or -1 for failure in which case target is not moved. + */ + int SearchInTarget(const wxString& text); + + /** + Find some text starting at the search anchor. + Does not ensure the selection is visible. + */ + int SearchNext(int flags, const wxString& text); + + /** + Find some text starting at the search anchor and moving backwards. + Does not ensure the selection is visible. + */ + int SearchPrev(int flags, const wxString& text); + + /** + Select all the text in the document. + */ + void SelectAll(); + + /** + Duplicate the selection. If selection empty duplicate the line containing the + caret. + */ + void SelectionDuplicate(); + + /** + Is the selection rectangular? The alternative is the more common stream + selection. + */ + bool SelectionIsRectangle(); + + /** + Send a message to Scintilla + */ + long SendMsg(int msg, long wp = 0, long lp = 0); + + /** + Set the selection anchor to a position. The anchor is the opposite + end of the selection from the caret. + */ + void SetAnchor(int posAnchor); + + /** + Sets whether a backspace pressed when caret is within indentation unindents. + */ + void SetBackSpaceUnIndents(bool bsUnIndents); + + /** + If drawing is buffered then each line of text is drawn into a bitmap buffer + before drawing it to the screen to avoid flicker. + */ + void SetBufferedDraw(bool buffered); + + /** + Set the foreground colour of the caret. + */ + void SetCaretForeground(const wxColour& fore); + + /** + Set background alpha of the caret line. + */ + void SetCaretLineBackAlpha(int alpha); + + /** + Set the colour of the background of the line containing the caret. + */ + void SetCaretLineBackground(const wxColour& back); + + /** + Display the background of the line containing the caret in a different colour. + */ + void SetCaretLineVisible(bool show); + + /** + Get the time in milliseconds that the caret is on and off. 0 = steady on. + */ + void SetCaretPeriod(int periodMilliseconds); + + /** + Stop the caret preferred x position changing when the user types. + */ + void SetCaretSticky(bool useCaretStickyBehaviour); + + /** + Set the width of the insert mode caret. + */ + void SetCaretWidth(int pixelWidth); + + /** + Reset the set of characters for whitespace and word characters to the defaults. + */ + void SetCharsDefault(); + + /** + Set the code page used to interpret the bytes of the document as characters. + */ + void SetCodePage(int codePage); + + /** + Change the way control characters are displayed: + If symbol is 32, keep the drawn way, else, use the given character. + */ + void SetControlCharSymbol(int symbol); + + /** + Sets the position of the caret. + */ + void SetCurrentPos(int pos); + + /** + Change the document object used. + */ + void SetDocPointer(void* docPointer); + + /** + Set the current end of line mode. + */ + void SetEOLMode(int eolMode); + + /** + Change the colour used in edge indication. + */ + void SetEdgeColour(const wxColour& edgeColour); + + /** + Set the column number of the edge. + If text goes past the edge then it is highlighted. + */ + void SetEdgeColumn(int column); + + /** + The edge may be displayed by a line (EDGE_LINE) or by highlighting text that + goes beyond it (EDGE_BACKGROUND) or not displayed at all (EDGE_NONE). + */ + void SetEdgeMode(int mode); + + /** + Sets the scroll range so that maximum scroll position has + the last line at the bottom of the view (default). + Setting this to @false allows scrolling one page below the last line. + */ + void SetEndAtLastLine(bool endAtLastLine); + + /** + Show the children of a header line. + */ + void SetFoldExpanded(int line, bool expanded); + + /** + Set some style options for folding. + */ + void SetFoldFlags(int flags); + + /** + Set the fold level of a line. + This encodes an integer level along with flags indicating whether the + line is a header and whether it is effectively white space. + */ + void SetFoldLevel(int line, int level); + + /** + Set the colours used as a chequerboard pattern in the fold margin + */ + void SetFoldMarginColour(bool useSetting, const wxColour& back); + + /** + + */ + void SetFoldMarginHiColour(bool useSetting, const wxColour& fore); + + /** + Set the horizontal scrollbar to use instead of the ont that's built-in. + */ + void SetHScrollBar(wxScrollBar* bar); + + /** + Set the highlighted indentation guide column. + 0 = no highlighted guide. + */ + void SetHighlightGuide(int column); + + /** + Set a back colour for active hotspots. + */ + void SetHotspotActiveBackground(bool useSetting, + const wxColour& back); + + /** + Set a fore colour for active hotspots. + */ + void SetHotspotActiveForeground(bool useSetting, + const wxColour& fore); + + /** + Enable / Disable underlining active hotspots. + */ + void SetHotspotActiveUnderline(bool underline); + + /** + Limit hotspots to single line so hotspots on two lines don't merge. + */ + void SetHotspotSingleLine(bool singleLine); + + /** + Set the number of spaces used for one level of indentation. + */ + void SetIndent(int indentSize); + + /** + Show or hide indentation guides. + */ + void SetIndentationGuides(bool show); + + /** + Set up the key words used by the lexer. + */ + void SetKeyWords(int keywordSet, const wxString& keyWords); + + /** + + */ + void SetLastKeydownProcessed(bool val); + + /** + Sets the degree of caching of layout information. + */ + void SetLayoutCache(int mode); + + /** + Set the lexing language of the document. + */ + void SetLexer(int lexer); + + /** + Set the lexing language of the document based on string name. + */ + void SetLexerLanguage(const wxString& language); + + /** + Change the indentation of a line to a number of columns. + */ + void SetLineIndentation(int line, int indentSize); + + /** + Used to hold extra styling information for each line. + */ + void SetLineState(int line, int state); + + /** + Sets the size in pixels of the left margin. + */ + void SetMarginLeft(int pixelWidth); + + /** + Set a mask that determines which markers are displayed in a margin. + */ + void SetMarginMask(int margin, int mask); + + /** + Sets the size in pixels of the right margin. + */ + void SetMarginRight(int pixelWidth); + + /** + Make a margin sensitive or insensitive to mouse clicks. + */ + void SetMarginSensitive(int margin, bool sensitive); + + /** + Set a margin to be either numeric or symbolic. + */ + void SetMarginType(int margin, int marginType); + + /** + Set the width of a margin to a width expressed in pixels. + */ + void SetMarginWidth(int margin, int pixelWidth); + + /** + Set the left and right margin in the edit area, measured in pixels. + */ + void SetMargins(int left, int right); + + /** + Set which document modification events are sent to the container. + */ + void SetModEventMask(int mask); + + /** + Set whether the mouse is captured when its button is pressed. + */ + void SetMouseDownCaptures(bool captures); + + /** + Sets the time the mouse must sit still to generate a mouse dwell event. + */ + void SetMouseDwellTime(int periodMilliseconds); + + /** + Set to overtype (@true) or insert mode. + */ + void SetOvertype(bool overtype); + + /** + Enable/Disable convert-on-paste for line endings + */ + void SetPasteConvertEndings(bool convert); + + /** + Modify colours when printing for clearer printed text. + */ + void SetPrintColourMode(int mode); + + /** + Sets the print magnification added to the point size of each style for printing. + */ + void SetPrintMagnification(int magnification); + + /** + Set printing to line wrapped (SC_WRAP_WORD) or not line wrapped (SC_WRAP_NONE). + */ + void SetPrintWrapMode(int mode); + + /** + Set up a value that may be used by a lexer for some optional feature. + */ + void SetProperty(const wxString& key, const wxString& value); + + /** + Set to read only or read write. + */ + void SetReadOnly(bool readOnly); + + /** + Sets the cursor to one of the SC_CURSOR* values. + */ + void SetSTCCursor(int cursorType); + + /** + Change internal focus flag. + */ + void SetSTCFocus(bool focus); + + /** + Remember the current position in the undo history as the position + at which the document was saved. + */ + void SetSavePoint(); + + /** + Sets the document width assumed for scrolling. + */ + void SetScrollWidth(int pixelWidth); + + /** + Set the search flags used by SearchInTarget. + */ + void SetSearchFlags(int flags); + + /** + Set the alpha of the selection. + */ + void SetSelAlpha(int alpha); + + /** + Set the background colour of the selection and whether to use this setting. + */ + void SetSelBackground(bool useSetting, const wxColour& back); + + /** + Set the foreground colour of the selection and whether to use this setting. + */ + void SetSelForeground(bool useSetting, const wxColour& fore); + + /** + Select a range of text. + */ + void SetSelection(int start, int end); + + /** + Sets the position that ends the selection - this becomes the currentPosition. + */ + void SetSelectionEnd(int pos); + + /** + Set the selection mode to stream (SC_SEL_STREAM) or rectangular + (SC_SEL_RECTANGLE) or + by lines (SC_SEL_LINES). + */ + void SetSelectionMode(int mode); + + /** + Sets the position that starts the selection - this becomes the anchor. + */ + void SetSelectionStart(int pos); + + /** + Change error status - 0 = OK. + */ + void SetStatus(int statusCode); + + /** + Divide each styling byte into lexical class bits (default: 5) and indicator + bits (default: 3). If a lexer requires more than 32 lexical states, then this + is used to expand the possible states. + */ + void SetStyleBits(int bits); + + /** + Set the styles for a segment of the document. + */ + void SetStyleBytes(int length, char* styleBytes); + + /** + Change style from current styling position for length characters to a style + and move the current styling position to after this newly styled segment. + */ + void SetStyling(int length, int style); + + /** + Sets whether a tab pressed when caret is within indentation indents. + */ + void SetTabIndents(bool tabIndents); + + /** + Change the visible size of a tab to be a multiple of the width of a space + character. + */ + void SetTabWidth(int tabWidth); + + /** + Sets the position that ends the target which is used for updating the + document without affecting the scroll position. + */ + void SetTargetEnd(int pos); + + /** + Sets the position that starts the target which is used for updating the + document without affecting the scroll position. + */ + void SetTargetStart(int pos); + + /** + Replace the contents of the document with the argument text. + */ + void SetText(const wxString& text); + + /** + Replace the contents of the document with the argument text. + */ + void SetTextRaw(const char* text); + + /** + In twoPhaseDraw mode, drawing is performed in two phases, first the background + and then the foreground. This avoids chopping off characters that overlap the + next run. + */ + void SetTwoPhaseDraw(bool twoPhase); + + /** + Choose between collecting actions into the undo + history and discarding them. + */ + void SetUndoCollection(bool collectUndo); + + /** + Specify whether anti-aliased fonts should be used. Will have no effect + on some platforms, but on some (wxMac for example) can greatly improve + performance. + */ + void SetUseAntiAliasing(bool useAA); + + /** + Show or hide the horizontal scroll bar. + */ + void SetUseHorizontalScrollBar(bool show); + + /** + Indentation will only use space characters if useTabs is @false, otherwise + it will use a combination of tabs and spaces. + */ + void SetUseTabs(bool useTabs); + + /** + Show or hide the vertical scroll bar. + */ + void SetUseVerticalScrollBar(bool show); + + /** + Set the vertical scrollbar to use instead of the ont that's built-in. + */ + void SetVScrollBar(wxScrollBar* bar); + + /** + Make the end of line characters visible or invisible. + */ + void SetViewEOL(bool visible); + + /** + Make white space characters invisible, always visible or visible outside + indentation. + */ + void SetViewWhiteSpace(int viewWS); + + /** + Set the way the display area is determined when a particular line + is to be moved to by Find, FindNext, GotoLine, etc. + */ + void SetVisiblePolicy(int visiblePolicy, int visibleSlop); + + /** + Set the background colour of all whitespace and whether to use this setting. + */ + void SetWhitespaceBackground(bool useSetting, + const wxColour& back); + + /** + Set the set of characters making up whitespace for when moving or selecting by + word. + Should be called after SetWordChars. + */ + void SetWhitespaceChars(const wxString& characters); + + /** + Set the foreground colour of all whitespace and whether to use this setting. + */ + void SetWhitespaceForeground(bool useSetting, + const wxColour& fore); + + /** + Set the set of characters making up words for when moving or selecting by word. + First sets deaults like SetCharsDefault. + */ + void SetWordChars(const wxString& characters); + + /** + Sets whether text is word wrapped. + */ + void SetWrapMode(int mode); + + /** + Set the start indent for wrapped lines. + */ + void SetWrapStartIndent(int indent); + + /** + Set the display mode of visual flags for wrapped lines. + */ + void SetWrapVisualFlags(int wrapVisualFlags); + + /** + Set the location of visual flags for wrapped lines. + */ + void SetWrapVisualFlagsLocation(int wrapVisualFlagsLocation); + + /** + Set the way the caret is kept visible when going sideway. + The exclusion zone is given in pixels. + */ + void SetXCaretPolicy(int caretPolicy, int caretSlop); + + /** + Get and Set the xOffset (ie, horizonal scroll position). + */ + void SetXOffset(int newOffset); + + /** + Set the way the line the caret is on is kept visible. + The exclusion zone is given in lines. + */ + void SetYCaretPolicy(int caretPolicy, int caretSlop); + + /** + Set the zoom level. This number of points is added to the size of all fonts. + It may be positive to magnify or negative to reduce. + */ + void SetZoom(int zoom); + + /** + Make a range of lines visible. + */ + void ShowLines(int lineStart, int lineEnd); + + /** + Start notifying the container of all key presses and commands. + */ + void StartRecord(); + + /** + Set the current styling position to pos and the styling mask to mask. + The styling mask can be used to protect some bits in each styling byte from + modification. + */ + void StartStyling(int pos, int mask); + + /** + Stop notifying the container of all key presses and commands. + */ + void StopRecord(); + + /** + Move caret to bottom of page, or one page down if already at bottom of page. + */ + void StutteredPageDown(); + + /** + Move caret to bottom of page, or one page down if already at bottom of page, + extending selection to new caret position. + */ + void StutteredPageDownExtend(); + + /** + Move caret to top of page, or one page up if already at top of page. + */ + void StutteredPageUp(); + + /** + Move caret to top of page, or one page up if already at top of page, extending + selection to new caret position. + */ + void StutteredPageUpExtend(); + + /** + Clear all the styles and make equivalent to the global default style. + */ + void StyleClearAll(); + + /** + Reset the default style to its state at startup + */ + void StyleResetDefault(); + + /** + Set the background colour of a style. + */ + void StyleSetBackground(int style, const wxColour& back); + + /** + Set a style to be bold or not. + */ + void StyleSetBold(int style, bool bold); + + /** + Set a style to be mixed case, or to force upper or lower case. + */ + void StyleSetCase(int style, int caseForce); + + /** + Set a style to be changeable or not (read only). + Experimental feature, currently buggy. + */ + void StyleSetChangeable(int style, bool changeable); + + /** + Set the character set of the font in a style. Converts the Scintilla + character set values to a wxFontEncoding. + */ + void StyleSetCharacterSet(int style, int characterSet); + + /** + Set a style to have its end of line filled or not. + */ + void StyleSetEOLFilled(int style, bool filled); + + /** + Set the font of a style. + */ + void StyleSetFaceName(int style, const wxString& fontName); + + /** + Set style size, face, bold, italic, and underline attributes from + a wxFont's attributes. + */ + void StyleSetFont(int styleNum, wxFont& font); + + /** + Set all font style attributes at once. + */ + void StyleSetFontAttr(int styleNum, int size, + const wxString& faceName, + bool bold, + bool italic, + bool underline, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + + /** + Set the font encoding to be used by a style. + */ + void StyleSetFontEncoding(int style, wxFontEncoding encoding); + + /** + Set the foreground colour of a style. + */ + void StyleSetForeground(int style, const wxColour& fore); + + /** + Set a style to be a hotspot or not. + */ + void StyleSetHotSpot(int style, bool hotspot); + + /** + Set a style to be italic or not. + */ + void StyleSetItalic(int style, bool italic); + + /** + Set the size of characters of a style. + */ + void StyleSetSize(int style, int sizePoints); + + /** + Extract style settings from a spec-string which is composed of one or + more of the following comma separated elements: + bold turns on bold + italic turns on italics + fore:[name or #RRGGBB] sets the foreground colour + back:[name or #RRGGBB] sets the background colour + face:[facename] sets the font face name to use + size:[num] sets the font size in points + eol turns on eol filling + underline turns on underlining + */ + void StyleSetSpec(int styleNum, const wxString& spec); + + /** + Set a style to be underlined or not. + */ + void StyleSetUnderline(int style, bool underline); + + /** + Set a style to be visible or not. + */ + void StyleSetVisible(int style, bool visible); + + /** + If selection is empty or all on one line replace the selection with a tab + character. + If more than one line selected, indent the lines. + */ +#define void Tab() /* implementation is private */ + + /** + Make the target range start and end be the same as the selection range start + and end. + */ + void TargetFromSelection(); + + /** + Retrieve the height of a particular line of text in pixels. + */ + int TextHeight(int line); + + /** + Measure the pixel width of some text in a particular style. + NUL terminated text argument. + Does not handle tab or control characters. + */ + int TextWidth(int style, const wxString& text); + + /** + Switch between sticky and non-sticky: meant to be bound to a key. + */ + void ToggleCaretSticky(); + + /** + Switch a header line between expanded and contracted. + */ + void ToggleFold(int line); + + /** + Undo one action in the undo history. + */ + void Undo(); + + /** + Transform the selection to upper case. + */ + void UpperCase(); + + /** + Set whether a pop up menu is displayed automatically when the user presses + the wrong mouse button. + */ + void UsePopUp(bool allowPopUp); + + /** + Display a list of strings and send notification when user chooses one. + */ + void UserListShow(int listType, const wxString& itemList); + + /** + Move caret to before first visible character on line. + If already there move to first character on line. + */ + void VCHome(); + + /** + Like VCHome but extending selection to new caret position. + */ + void VCHomeExtend(); + + /** + Move caret to before first visible character on line. + If already there move to first character on line. + In either case, extend rectangular selection to new caret position. + */ + void VCHomeRectExtend(); + + /** + + */ + void VCHomeWrap(); + + /** + + */ + void VCHomeWrapExtend(); + + /** + Find the display line of a document line taking hidden lines into account. + */ + int VisibleFromDocLine(int line); + + /** + Get position of end of word. + */ + int WordEndPosition(int pos, bool onlyWordCharacters); + + /** + Move caret left one word. + */ + void WordLeft(); + + /** + Move caret left one word, position cursor at end of word. + */ + void WordLeftEnd(); + + /** + Move caret left one word, position cursor at end of word, extending selection + to new caret position. + */ + void WordLeftEndExtend(); + + /** + Move caret left one word extending selection to new caret position. + */ + void WordLeftExtend(); + + /** + Move to the previous change in capitalisation. + */ + void WordPartLeft(); + + /** + Move to the previous change in capitalisation extending selection + to new caret position. + */ + void WordPartLeftExtend(); + + /** + Move to the change next in capitalisation. + */ + void WordPartRight(); + + /** + Move to the next change in capitalisation extending selection + to new caret position. + */ + void WordPartRightExtend(); + + /** + Move caret right one word. + */ + void WordRight(); + + /** + Move caret right one word, position cursor at end of word. + */ + void WordRightEnd(); + + /** + Move caret right one word, position cursor at end of word, extending selection + to new caret position. + */ + void WordRightEndExtend(); + + /** + Move caret right one word extending selection to new caret position. + */ + void WordRightExtend(); + + /** + Get position of start of word. + */ + int WordStartPosition(int pos, bool onlyWordCharacters); + + /** + The number of display lines needed to wrap a document line + */ + int WrapCount(int line); + + /** + Magnify the displayed text by increasing the sizes by 1 point. + */ + void ZoomIn(); + + /** + Make the displayed text smaller by decreasing the sizes by 1 point. + */ + void ZoomOut(); +}; diff --git a/interface/stdpaths.h b/interface/stdpaths.h new file mode 100644 index 0000000000..745fe760d5 --- /dev/null +++ b/interface/stdpaths.h @@ -0,0 +1,248 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stdpaths.h +// Purpose: documentation for wxStandardPaths class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStandardPaths + @wxheader{stdpaths.h} + + wxStandardPaths returns the standard locations in the file system and should be + used by applications to find their data files in a portable way. + + In the description of the methods below, the example return values are given + for the Unix, Windows and Mac OS X systems, however please note that these are + just the examples and the actual values may differ. For example, under Windows: + the system administrator may change the standard directories locations, i.e. + the Windows directory may be named @c W:\Win2003 instead of + the default @c C:\Windows. + + The strings @c @e appname and @c @e username should be + replaced with the value returned by wxApp::GetAppName + and the name of the currently logged in user, respectively. The string + @c @e prefix is only used under Unix and is @c /usr/local by + default but may be changed using wxStandardPaths::SetInstallPrefix. + + The directories returned by the methods of this class may or may not exist. If + they don't exist, it's up to the caller to create them, wxStandardPaths doesn't + do it. + + Finally note that these functions only work with standardly packaged + applications. I.e. under Unix you should follow the standard installation + conventions and under Mac you should create your application bundle according + to the Apple guidelines. Again, this class doesn't help you to do it. + + This class is MT-safe: its methods may be called concurrently from different + threads without additional locking. + + @library{wxbase} + @category{file} + + @seealso + wxFileConfig +*/ +class wxStandardPaths +{ +public: + /** + Returns reference to the unique global standard paths object. + */ +#define static wxStandardPathsBase Get() /* implementation is private */ + + /** + Return the directory containing the system config files. + + Example return values: + + Unix: @c /etc + Windows: @c C:\Documents and Settings\All Users\Application Data + Mac: @c /Library/Preferences + + @sa wxFileConfig + */ + wxString GetConfigDir(); + + /** + Return the location of the applications global, i.e. not user-specific, + data files. + + Example return values: + + Unix: @c @e prefix/share/@e appname + Windows: the directory where the executable file is located + Mac: @c @e appname.app/Contents/SharedSupport bundle subdirectory + + @sa GetLocalDataDir() + */ + wxString GetDataDir(); + + /** + Return the directory containing the current user's documents. + + Example return values: + + Unix: @c ~ (the home directory) + Windows: @c C:\Documents and Settings\@e username\Documents + Mac: @c ~/Documents + + This function is new since wxWidgets version 2.7.0 + */ + wxString GetDocumentsDir(); + + /** + Return the directory and the filename for the current executable. + + Example return values: + + Unix: @c /usr/local/bin/exename + Windows: @c C:\Programs\AppFolder\exename.exe + Mac: @c /Programs/exename + */ + wxString GetExecutablePath(); + + /** + @b Note: This function is only available under Unix. + + Return the program installation prefix, e.g. @c /usr, @c /opt or + @c /home/zeitlin. + + If the prefix had been previously by + SetInstallPrefix(), returns that + value, otherwise tries to determine it automatically (Linux only right + now) and finally returns the default @c /usr/local value if it failed. + */ + wxString GetInstallPrefix(); + + /** + Return the location for application data files which are host-specific and + can't, or shouldn't, be shared with the other machines. + + This is the same as GetDataDir() except + under Unix where it returns @c /etc/@e appname. + */ + wxString GetLocalDataDir(); + + /** + Return the localized resources directory containing the resource files of the + specified category for the given language. + + In general this is just the same as @e lang subdirectory of + GetResourcesDir() (or + @c @e lang.lproj under Mac OS X) but is something quite + different for message catalog category under Unix where it returns the standard + @c @e prefix/share/locale/@e lang/LC_MESSAGES directory. + + This function is new since wxWidgets version 2.7.0 + */ + wxString GetLocalizedResourcesDir(const wxString& lang, + ResourceCat category = ResourceCat_None); + + /** + Return the directory where the loadable modules (plugins) live. + + Example return values: + + Unix: @c @e prefix/lib/@e appname + Windows: the directory of the executable file + Mac: @c @e appname.app/Contents/PlugIns bundle subdirectory + + @sa wxDynamicLibrary + */ + wxString GetPluginsDir(); + + /** + Return the directory where the application resource files are located. The + resources are the auxiliary data files needed for the application to run and + include, for example, image and sound files it might use. + + This function is the same as GetDataDir() for + all platforms except Mac OS X. + + Example return values: + + Unix: @c @e prefix/share/@e appname + Windows: the directory where the executable file is located + Mac: @c @e appname.app/Contents/Resources bundle subdirectory + + This function is new since wxWidgets version 2.7.0 + + @sa GetLocalizedResourcesDir() + */ + wxString GetResourcesDir(); + + /** + Return the directory for storing temporary files. To create unique temporary + files, + it is best to use wxFileName::CreateTempFileName for correct behaviour when + multiple processes are attempting to create temporary files. + + This function is new since wxWidgets version 2.7.2 + */ + wxString GetTempDir(); + + /** + Return the directory for the user config files: + + Unix: @c ~ (the home directory) + Windows: @c C:\Documents and Settings\@e username\Application Data + Mac: @c ~/Library/Preferences + + Only use this method if you have a single configuration file to put in this + directory, otherwise GetUserDataDir() is + more appropriate. + */ + wxString GetUserConfigDir(); + + /** + Return the directory for the user-dependent application data files: + + Unix: @c ~/.@e appname + Windows: @c C:\Documents and Settings\@e username\Application Data\@e + appname + Mac: @c ~/Library/Application Support/@e appname + */ + wxString GetUserDataDir(); + + /** + Return the directory for user data files which shouldn't be shared with + the other machines. + + This is the same as GetUserDataDir() for + all platforms except Windows where it returns + @c C:\Documents and Settings\@e username\Local Settings\Application Data\@e + appname + */ + wxString GetUserLocalDataDir(); + + /** + @b Note: This function is only available under Unix. + + Lets wxStandardPaths know about the real program installation prefix on a Unix + system. By default, the value returned by + GetInstallPrefix() is used. + + Although under Linux systems the program prefix may usually be determined + automatically, portable programs should call this function. Usually the prefix + is set during program configuration if using GNU autotools and so it is enough + to pass its value defined in @c config.h to this function. + */ + void SetInstallPrefix(const wxString& prefix); + + /** + Controls what application information is used when constructing paths that + should be unique to this program, such as the application data directory, the + plugins directory on Unix, etc. + + Valid values for @e info are @c AppInfo_None and either one or + combination of @c AppInfo_AppName and @c AppInfo_VendorName. The + first one tells this class to not use neither application nor vendor name in + the paths. + + By default, only the application name is used under Unix systems but both + application and vendor names are used under Windows and Mac. + */ + void UseAppInfo(int info); +}; diff --git a/interface/stockitem.h b/interface/stockitem.h new file mode 100644 index 0000000000..3bcf0b2d08 --- /dev/null +++ b/interface/stockitem.h @@ -0,0 +1,29 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: stockitem.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + Returns label that should be used for given @e id element. + + @param id + given id of the wxMenuItem, wxButton, wxToolBar tool, etc. + + @param withCodes + if @false then strip accelerator code from the label; + useful for getting labels without accelerator char code like for toolbar + tooltip or + on platforms without traditional keyboard like smartphones + + @param accelerator + optional accelerator string automatically added to label; useful + for building labels for wxMenuItem +*/ +wxString wxGetStockLabel(wxWindowID id, bool withCodes = @true, + const wxString& accelerator = wxEmptyString); + + + \ No newline at end of file diff --git a/interface/stopwatch.h b/interface/stopwatch.h new file mode 100644 index 0000000000..8df3137f8a --- /dev/null +++ b/interface/stopwatch.h @@ -0,0 +1,96 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stopwatch.h +// Purpose: documentation for wxStopWatch class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStopWatch + @wxheader{stopwatch.h} + + The wxStopWatch class allow you to measure time intervals. For example, you may + use it to measure the time elapsed by some function: + + @code + wxStopWatch sw; + CallLongRunningFunction(); + wxLogMessage("The long running function took %ldms to execute", + sw.Time()); + sw.Pause(); + ... stopwatch is stopped now ... + sw.Resume(); + CallLongRunningFunction(); + wxLogMessage("And calling it twice took $ldms in all", sw.Time()); + @endcode + + @library{wxbase} + @category{misc} + + @seealso + wxTimer +*/ +class wxStopWatch +{ +public: + /** + Constructor. This starts the stop watch. + */ + wxStopWatch(); + + /** + Pauses the stop watch. Call Resume() to resume + time measuring again. + + If this method is called several times, @c Resume() must be called the same + number of times to really resume the stop watch. You may, however, call + Start() to resume it unconditionally. + */ + void Pause(); + + /** + Resumes the stop watch which had been paused with + Pause(). + */ + void Resume(); + + /** + (Re)starts the stop watch with a given initial value. + */ + void Start(long milliseconds = 0); + + /** + Returns the time in milliseconds since the start (or restart) or the last call + of + Pause(). + */ + long Time(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Returns the number of seconds since local time 00:00:00 Jan 1st 1970. + + @sa wxDateTime::Now +*/ +long wxGetLocalTime(); + +/** + Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. + + @sa wxDateTime::Now +*/ +long wxGetUTCTime(); + +/** + Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. + + @sa wxDateTime::Now, wxLongLong +*/ +wxLongLong wxGetLocalTimeMillis(); + diff --git a/interface/strconv.h b/interface/strconv.h new file mode 100644 index 0000000000..e734ef3f22 --- /dev/null +++ b/interface/strconv.h @@ -0,0 +1,470 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: strconv.h +// Purpose: documentation for wxMBConvUTF7 class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMBConvUTF7 + @wxheader{strconv.h} + + This class converts between the UTF-7 encoding and Unicode. + It has one predefined instance, @b wxConvUTF7. + + @b WARNING: this class is not implemented yet. + + @library{wxbase} + @category{FIXME} + + @seealso + wxMBConvUTF8, @ref overview_mbconvclasses "wxMBConv classes overview" +*/ +class wxMBConvUTF7 : public wxMBConv +{ +public: + /** + Converts from UTF-7 encoding to Unicode. Returns the size of the destination + buffer. + */ +#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + + /** + Converts from Unicode to UTF-7 encoding. Returns the size of the destination + buffer. + */ +#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ +}; + + +/** + @class wxMBConvUTF8 + @wxheader{strconv.h} + + This class converts between the UTF-8 encoding and Unicode. + It has one predefined instance, @b wxConvUTF8. + + @library{wxbase} + @category{FIXME} + + @seealso + wxMBConvUTF7, @ref overview_mbconvclasses "wxMBConv classes overview" +*/ +class wxMBConvUTF8 : public wxMBConv +{ +public: + /** + Converts from UTF-8 encoding to Unicode. Returns the size of the destination + buffer. + */ +#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + + /** + Converts from Unicode to UTF-8 encoding. Returns the size of the destination + buffer. + */ +#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ +}; + + +/** + @class wxMBConvUTF16 + @wxheader{strconv.h} + + This class is used to convert between multibyte encodings and UTF-16 Unicode + encoding (also known as UCS-2). Unlike UTF-8 encoding, + UTF-16 uses words and not bytes and hence depends on the byte ordering: + big or little endian. Hence this class is provided in two versions: + wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself is just a typedef + for one of them (native for the given platform, e.g. LE under Windows and BE + under Mac). + + @library{wxbase} + @category{FIXME} + + @seealso + wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconvclasses "wxMBConv classes + overview" +*/ +class wxMBConvUTF16 : public wxMBConv +{ +public: + /** + Converts from UTF-16 encoding to Unicode. Returns the size of the destination + buffer. + */ +#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + + /** + Converts from Unicode to UTF-16 encoding. Returns the size of the destination + buffer. + */ +#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ +}; + + +/** + @class wxCSConv + @wxheader{strconv.h} + + This class converts between any character sets and Unicode. + It has one predefined instance, @b wxConvLocal, for the + default user character set. + + @library{wxbase} + @category{FIXME} + + @seealso + wxMBConv, wxEncodingConverter, @ref overview_mbconvclasses "wxMBConv classes + overview" +*/ +class wxCSConv : public wxMBConv +{ +public: + //@{ + /** + 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 (or the + encoding) is not recognized, ISO 8859-1 is used as fall back. + */ + wxCSConv(const wxChar* charset); + wxCSConv(wxFontEncoding encoding); + //@} + + /** + Destructor frees any resources needed to perform the conversion. + */ + ~wxCSConv(); + + /** + Returns @true if the charset (or the encoding) given at constructor is really + available to use. Returns @false if ISO 8859-1 will be used instead. + + Note this does not mean that a given string will be correctly converted. + A malformed string may still make conversion functions return @c wxCONV_FAILED. + + This function is new since wxWidgets version 2.8.2 + */ +#define bool IsOk() /* implementation is private */ + + /** + Converts from the selected character set to Unicode. Returns length of string + written to destination buffer. + */ +#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + + /** + Converts from Unicode to the selected character set. Returns length of string + written to destination buffer. + */ +#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ +}; + + +/** + @class wxMBConvFile + @wxheader{strconv.h} + + This class used to define the class instance + @b wxConvFileName, but nowadays @b wxConvFileName is + either of type wxConvLibc (on most platforms) or wxConvUTF8 + (on MacOS X). @b wxConvFileName converts filenames between + filesystem multibyte encoding and Unicode. @b wxConvFileName + can also be set to a something else at run-time which is used + e.g. by wxGTK to use a class which checks the environment + variable @b G_FILESYSTEM_ENCODING indicating that filenames + should not be interpreted as UTF8 and also for converting + invalid UTF8 characters (e.g. if there is a filename in iso8859_1) + to strings with octal values. + + Since some platforms (such as Win32) use Unicode in the filenames, + and others (such as Unix) use multibyte encodings, this class should only + be used directly if wxMBFILES is defined to 1. A convenience macro, + wxFNCONV, is defined to wxConvFileName-cWX2MB in this case. You could + use it like this: + + @code + wxChar *name = wxT("rawfile.doc"); + FILE *fil = fopen(wxFNCONV(name), "r"); + @endcode + + (although it would be better to use wxFopen(name, wxT("r")) in this case.) + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_mbconvclasses "wxMBConv classes overview" +*/ +class wxMBConvFile : public wxMBConv +{ +public: + /** + Converts from multibyte filename encoding to Unicode. Returns the size of the + destination buffer. + */ +#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + + /** + Converts from Unicode to multibyte filename encoding. Returns the size of the + destination buffer. + */ +#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ +}; + + +/** + @class wxMBConvUTF32 + @wxheader{strconv.h} + + This class is used to convert between multibyte encodings and UTF-32 Unicode + encoding (also known as UCS-4). Unlike UTF-8 encoding, + UTF-32 uses (double) words and not bytes and hence depends on the byte ordering: + big or little endian. Hence this class is provided in two versions: + wxMBConvUTF32LE and wxMBConvUTF32BE and wxMBConvUTF32 itself is just a typedef + for one of them (native for the given platform, e.g. LE under Windows and BE + under Mac). + + @library{wxbase} + @category{FIXME} + + @seealso + wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconvclasses "wxMBConv classes + overview" +*/ +class wxMBConvUTF32 : public wxMBConv +{ +public: + /** + Converts from UTF-32 encoding to Unicode. Returns the size of the destination + buffer. + */ +#define size_t MB2WC(wchar_t* buf, const char* psz, size_t n) /* implementation is private */ + + /** + Converts from Unicode to UTF-32 encoding. Returns the size of the destination + buffer. + */ +#define size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ +}; + + +/** + @class wxMBConv + @wxheader{strconv.h} + + This class is the base class of a hierarchy of classes capable of converting + text strings between multibyte (SBCS or DBCS) encodings and Unicode. + + In the documentation for this and related classes please notice that + length of the string refers to the number of characters in the string + not counting the terminating @c NUL, if any. While the size of the string + is the total number of bytes in the string, including any trailing @c NUL. + Thus, length of wide character string @c L"foo" is 3 while its size can + be either 8 or 16 depending on whether @c wchar_t is 2 bytes (as + under Windows) or 4 (Unix). + + @library{wxbase} + @category{FIXME} + + @seealso + wxCSConv, wxEncodingConverter, @ref overview_mbconvclasses "wxMBConv classes + overview" +*/ +class wxMBConv +{ +public: + /** + Trivial default constructor. + */ + wxMBConv(); + + /** + This pure virtual function is overridden in each of the derived classes to + return a new copy of the object it is called on. It is used for copying the + conversion objects while preserving their dynamic type. + */ + virtual wxMBConv * Clone(); + + /** + This function has the same semantics as ToWChar() + except that it converts a wide string to multibyte one. + */ + virtual size_t FromWChar(char * dst, size_t dstLen, + const wchar_t * src, + size_t srcLen = wxNO_LEN); + + /** + This function returns 1 for most of the multibyte encodings in which the + string is terminated by a single @c NUL, 2 for UTF-16 and 4 for UTF-32 for + which the string is terminated with 2 and 4 @c NUL characters respectively. + The other cases are not currently supported and @c wxCONV_FAILED + (defined as -1) is returned for them. + */ + size_t GetMBNulLen(); + + /** + Returns the maximal value which can be returned by + GetMBNulLen() for any conversion object. Currently + this value is 4. + + This method can be used to allocate the buffer with enough space for the + trailing @c NUL characters for any encoding. + */ + const size_t GetMaxMBNulLen(); + + /** + This function is deprecated, please use ToWChar() instead + + Converts from a string @e in in multibyte encoding to Unicode putting up to + @e outLen characters into the buffer @e out. + + If @e out is @NULL, only the length of the string which would result from + the conversion is calculated and returned. Note that this is the length and not + size, i.e. the returned value does not include the trailing @c NUL. But + when the function is called with a non-@NULL @e out buffer, the @e outLen + parameter should be one more to allow to properly @c NUL-terminate the string. + + @param out + The output buffer, may be @NULL if the caller is only + interested in the length of the resulting string + + @param in + The NUL-terminated input string, cannot be @NULL + + @param outLen + The length of the output buffer but including + NUL, ignored if out is @NULL + + @returns The length of the converted string excluding the trailing NUL. + */ +#define virtual size_t MB2WC(wchar_t * out, const char * in, + size_t outLen) /* implementation is private */ + + /** + The most general function for converting a multibyte string to a wide string. + The main case is when @e dst is not @NULL and @e srcLen is not + @c wxNO_LEN (which is defined as @c (size_t)-1): then + the function converts exactly @e srcLen bytes starting at @e src into + wide string which it output to @e dst. If the length of the resulting wide + string is greater than @e dstLen, an error is returned. Note that if + @e srcLen bytes don't include @c NUL characters, the resulting wide string is + not @c NUL-terminated neither. + + If @e srcLen is @c wxNO_LEN, the function supposes that the string is + properly (i.e. as necessary for the encoding handled by this conversion) + @c NUL-terminated and converts the entire string, including any trailing @c NUL + bytes. In this case the wide string is also @c NUL-terminated. + + Finally, if @e dst is @NULL, the function returns the length of the needed + buffer. + */ + virtual size_t ToWChar(wchar_t * dst, size_t dstLen, + const char * src, + size_t srcLen = wxNO_LEN); + + /** + This function is deprecated, please use FromWChar() instead + + Converts from Unicode to multibyte encoding. The semantics of this function + (including the return value meaning) is the same as for + wxMBConv::MB2WC. + + Notice that when the function is called with a non-@NULL buffer, the + @e n parameter should be the size of the buffer and so it should take + into account the trailing @c NUL, which might take two or four bytes for some + encodings (UTF-16 and UTF-32) and not one. + */ +#define virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) /* implementation is private */ + + //@{ + /** + Converts from multibyte encoding to Unicode by calling + wxMBConv::MB2WC, allocating a temporary wxWCharBuffer to hold + the result. + + The first overload takes a @c NUL-terminated input string. The second one takes + a + string of exactly the specified length and the string may include or not the + trailing @c NUL character(s). If the string is not @c NUL-terminated, a + temporary + @c NUL-terminated copy of it suitable for passing to wxMBConv::MB2WC + is made, so it is more efficient to ensure that the string is does have the + appropriate number of @c NUL bytes (which is usually 1 but may be 2 or 4 + for UTF-16 or UTF-32, see wxMBConv::GetMBNulLen), + especially for long strings. + + If @e outLen is not-@NULL, it receives the length of the converted + string. + */ + const wxWCharBuffer cMB2WC(const char * in); + const wxWCharBuffer cMB2WC(const char * in, size_t inLen, + size_t outLen); + //@} + + //@{ + /** + Converts from multibyte encoding to the current wxChar type + (which depends on whether wxUSE_UNICODE is set to 1). If wxChar is char, + it returns the parameter unaltered. If wxChar is wchar_t, it returns the + result in a wxWCharBuffer. The macro wxMB2WXbuf is defined as the correct + return type (without const). + */ + const char* cMB2WX(const char* psz); + const wxWCharBuffer cMB2WX(const char* psz); + //@} + + //@{ + /** + Converts from Unicode to multibyte encoding by calling WC2MB, + allocating a temporary wxCharBuffer to hold the result. + + The second overload of this function allows to convert a string of the given + length @e inLen, whether it is @c NUL-terminated or not (for wide character + strings, unlike for the multibyte ones, a single @c NUL is always enough). + But notice that just as with @ref wxMBConv::mb2wc cMB2WC, it is more + efficient to pass an already terminated string to this function as otherwise a + copy is made internally. + + If @e outLen is not-@NULL, it receives the length of the converted + string. + */ + const wxCharBuffer cWC2MB(const wchar_t* in); + const wxCharBuffer cWC2MB(const wchar_t* in, size_t inLen, + size_t outLen); + //@} + + //@{ + /** + Converts from Unicode to the current wxChar type. If wxChar is wchar_t, + it returns the parameter unaltered. If wxChar is char, it returns the + result in a wxCharBuffer. The macro wxWC2WXbuf is defined as the correct + return type (without const). + */ + const wchar_t* cWC2WX(const wchar_t* psz); + const wxCharBuffer cWC2WX(const wchar_t* psz); + //@} + + //@{ + /** + Converts from the current wxChar type to multibyte encoding. If wxChar is char, + it returns the parameter unaltered. If wxChar is wchar_t, it returns the + result in a wxCharBuffer. The macro wxWX2MBbuf is defined as the correct + return type (without const). + */ + const char* cWX2MB(const wxChar* psz); + const wxCharBuffer cWX2MB(const wxChar* psz); + //@} + + //@{ + /** + Converts from the current wxChar type to Unicode. If wxChar is wchar_t, + it returns the parameter unaltered. If wxChar is char, it returns the + result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct + return type (without const). + */ + const wchar_t* cWX2WC(const wxChar* psz); + const wxWCharBuffer cWX2WC(const wxChar* psz); + //@} +}; diff --git a/interface/stream.h b/interface/stream.h new file mode 100644 index 0000000000..fb81c097c9 --- /dev/null +++ b/interface/stream.h @@ -0,0 +1,798 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stream.h +// Purpose: documentation for wxCountingOutputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCountingOutputStream + @wxheader{stream.h} + + wxCountingOutputStream is a specialized output stream which does not write any + data anywhere, + instead it counts how many bytes would get written if this were a normal + stream. This + can sometimes be useful or required if some data gets serialized to a stream or + compressed + by using stream compression and thus the final size of the stream cannot be + known other + than pretending to write the stream. One case where the resulting size would + have to be + known is if the data has to be written to a piece of memory and the memory has + to be + allocated before writing to it (which is probably always the case when writing + to a + memory stream). + + @library{wxbase} + @category{streams} +*/ +class wxCountingOutputStream : public wxOutputStream +{ +public: + /** + Creates a wxCountingOutputStream object. + */ + wxCountingOutputStream(); + + /** + Destructor. + */ + ~wxCountingOutputStream(); + + /** + Returns the current size of the stream. + */ + size_t GetSize(); +}; + + +/** + @class wxBufferedInputStream + @wxheader{stream.h} + + This stream acts as a cache. It caches the bytes read from the specified + input stream (See wxFilterInputStream). + It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes. + This class may not be used without some other stream to read the data + from (such as a file stream or a memory stream). + + @library{wxbase} + @category{streams} + + @seealso + wxStreamBuffer, wxInputStream, wxBufferedOutputStream +*/ +class wxBufferedInputStream : public wxFilterInputStream +{ +public: + +}; + + +/** + @class wxStreamBuffer + @wxheader{stream.h} + + + @library{wxbase} + @category{streams} + + @seealso + wxStreamBase +*/ +class wxStreamBuffer +{ +public: + //@{ + /** + Constructor. It initializes the stream buffer with the data of the specified + stream buffer. The new stream buffer has the same attributes, size, position + and they share the same buffer. This will cause problems if the stream to + which the stream buffer belong is destroyed and the newly cloned stream + buffer continues to be used, trying to call functions in the (destroyed) + stream. It is advised to use this feature only in very local area of the + program. + + @sa @ref setbufferio() wxStreamBuffer:SetBufferIO + */ + wxStreamBuffer(wxStreamBase& stream, BufMode mode); + wxStreamBuffer(BufMode mode); + wxStreamBuffer(const wxStreamBuffer& buffer); + //@} + + /** + Destructor. It finalizes all IO calls and frees all internal buffers if + necessary. + */ + wxStreamBuffer(); + + /** + Fill the IO buffer. + */ + bool FillBuffer(); + + /** + Toggles the fixed flag. Usually this flag is toggled at the same time as + @e flushable. This flag allows (when it has the @false value) or forbids + (when it has the @true value) the stream buffer to resize dynamically the IO + buffer. + + @sa SetBufferIO() + */ + void Fixed(bool fixed); + + /** + Flushes the IO buffer. + */ + bool FlushBuffer(); + + /** + Toggles the flushable flag. If @e flushable is disabled, no data are sent + to the parent stream. + */ + void Flushable(bool flushable); + + /** + Returns a pointer on the end of the stream buffer. + */ + void * GetBufferEnd(); + + /** + Returns a pointer on the current position of the stream buffer. + */ + void * GetBufferPos(); + + /** + Returns the size of the buffer. + */ + size_t GetBufferSize(); + + /** + Returns a pointer on the start of the stream buffer. + */ + void * GetBufferStart(); + + /** + Gets a single char from the stream buffer. It acts like the Read call. + + @sa Read() + */ + char GetChar(); + + /** + Returns the amount of available data in the buffer. + */ + size_t GetDataLeft(); + + /** + Returns the current position (counted in bytes) in the stream buffer. + */ + off_t GetIntPosition(); + + /** + Returns the amount of bytes read during the last IO call to the parent stream. + */ + size_t GetLastAccess(); + + /** + Puts a single char to the stream buffer. + + @sa Read() + */ + void PutChar(char c); + + //@{ + /** + Copies data to @e buffer. The function returns when @e buffer is full or when + there isn't + any more data in the current buffer. + + @sa Write() + */ + size_t Read(void * buffer, size_t size); + Return value size_t Read(wxStreamBuffer * buffer); + //@} + + /** + Resets to the initial state variables concerning the buffer. + */ + void ResetBuffer(); + + /** + Changes the current position. + + @e mode may be one of the following: + + + @b wxFromStart + + + The position is counted from the start of the stream. + + @b wxFromCurrent + + + The position is counted from the current position of the stream. + + @b wxFromEnd + + + The position is counted from the end of the stream. + + + @returns Upon successful completion, it returns the new offset as + measured in bytes from the beginning of the stream. + Otherwise, it returns wxInvalidOffset. + */ + off_t Seek(off_t pos, wxSeekMode mode); + + //@{ + /** + Destroys or invalidates the previous IO buffer and allocates a new one of the + specified size. + + @sa Fixed(), Flushable() + */ + void SetBufferIO(char* buffer_start, char* buffer_end); + Remarks See also +wxStreamBuffer constructor + +wxStreamBuffer::Fixed + +wxStreamBuffer::Flushable +void SetBufferIO(size_t bufsize); + //@} + + /** + Sets the current position (in bytes) in the stream buffer. + */ + void SetIntPosition(size_t pos); + + /** + Returns the parent stream of the stream buffer. + */ + wxStreamBase* Stream(); + + /** + Gets the current position in the stream. This position is calculated from + the @e real position in the stream and from the internal buffer position: so + it gives you the position in the @e real stream counted from the start of + the stream. + + @returns Returns the current position in the stream if possible, + wxInvalidOffset in the other case. + */ + off_t Tell(); + + /** + Truncates the buffer to the current position. + + Note: Truncate() cannot be used to enlarge the buffer. This is + usually not needed since the buffer expands automatically. + */ + void Truncate(); + + //@{ + /** + See Read(). + */ + size_t Write(const void * buffer, size_t size); + size_t Write(wxStreamBuffer * buffer); + //@} +}; + + +/** + @class wxOutputStream + @wxheader{stream.h} + + wxOutputStream is an abstract base class which may not be used directly. + + @library{wxbase} + @category{streams} +*/ +class wxOutputStream : public wxStreamBase +{ +public: + /** + Creates a dummy wxOutputStream object. + */ + wxOutputStream(); + + /** + Destructor. + */ + ~wxOutputStream(); + + /** + Closes the stream, returning @false if an error occurs. The + stream is closed implicitly in the destructor if Close() is not + called explicitly. + + If this stream wraps another stream or some other resource such + as a file, then the underlying resource is closed too if it is owned + by this stream, or left open otherwise. + */ + bool Close(); + + /** + Returns the number of bytes written during the last + Write(). It may return 0 even if there is no + error on the stream if it is only temporarily impossible to write to it. + */ + size_t LastWrite(); + + /** + Puts the specified character in the output queue and increments the + stream position. + */ +#define void PutC(char c) /* implementation is private */ + + /** + Changes the stream current position. + + @param pos + Offset to seek to. + + @param mode + One of wxFromStart, wxFromEnd, wxFromCurrent. + + @returns The new stream position or wxInvalidOffset on error. + */ + off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart); + + /** + Returns the current stream position. + */ + off_t TellO(); + + //@{ + /** + Reads data from the specified input stream and stores them + in the current stream. The data is read until an error is raised + by one of the two streams. + */ + wxOutputStream Write(const void * buffer, size_t size); + wxOutputStream Write(wxInputStream& stream_in); + //@} +}; + + +/** + @class wxFilterClassFactory + @wxheader{stream.h} + + Allows the creation of filter streams to handle compression formats such + as gzip and bzip2. + + For example, given a filename you can search for a factory that will + handle it and create a stream to decompress it: + + @code + factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT); + if (factory) + stream = factory-NewStream(new wxFFileInputStream(filename)); + @endcode + + wxFilterClassFactory::Find can also search + for a factory by MIME type, HTTP encoding or by wxFileSystem protocol. + The available factories can be enumerated + using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext". + + @library{wxbase} + @category{FIXME} + + @seealso + wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref + overview_wxarc "Archive formats such as zip" +*/ +class wxFilterClassFactory : public wxObject +{ +public: + /** + Returns @true if this factory can handle the given protocol, MIME type, HTTP + encoding or file extension. + + When using wxSTREAM_FILEEXT for the second parameter, the first parameter + can be a complete filename rather than just an extension. + */ + bool CanHandle(const wxString& protocol, + wxStreamProtocolType type = wxSTREAM_PROTOCOL); + + /** + A static member that finds a factory that can handle a given protocol, MIME + type, HTTP encoding or file extension. Returns a pointer to the class + factory if found, or @NULL otherwise. It does not give away ownership of the + factory. + + When using wxSTREAM_FILEEXT for the second parameter, the first parameter + can be a complete filename rather than just an extension. + */ + static const wxFilterClassFactory* Find(const wxString& protocol, + wxStreamProtocolType type = wxSTREAM_PROTOCOL); + + //@{ + /** + GetFirst and GetNext can be used to enumerate the available factories. + + For example, to list them: + GetFirst()/GetNext() return a pointer to a factory or @NULL if no more + are available. They do not give away ownership of the factory. + */ + static const wxFilterClassFactory* GetFirst(); + const wxFilterClassFactory* GetNext(); + //@} + + /** + Returns the wxFileSystem protocol supported by this factory. Equivalent + to wxString(*GetProtcols()). + */ + wxString GetProtocol(); + + /** + Returns the protocols, MIME types, HTTP encodings or file extensions + supported by this factory, as an array of null terminated strings. It does + not give away ownership of the array or strings. + + For example, to list the file extensions a factory supports: + */ + const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL); + + //@{ + /** + Create a new input or output stream to decompress or compress a given stream. + + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxFilterInputStream* NewStream(wxInputStream& stream); + wxFilterOutputStream* NewStream(wxOutputStream& stream); + wxFilterInputStream* NewStream(wxInputStream* stream); + wxFilterOutputStream* NewStream(wxOutputStream* stream); + //@} + + /** + Remove the file extension of @e location if it is one of the file + extensions handled by this factory. + */ + wxString PopExtension(const wxString& location); + + /** + Adds this class factory to the list returned + by @ref getfirst() GetFirst()/GetNext. + + It is not necessary to do this to use the filter streams. It is usually + used when implementing streams, typically the implementation will + add a static instance of its factory class. + + It can also be used to change the order of a factory already in the list, + bringing it to the front. This isn't a thread safe operation + so can't be done when other threads are running that will be using the list. + + The list does not take ownership of the factory. + */ + void PushFront(); + + /** + Removes this class factory from the list returned + by @ref getfirst() GetFirst()/GetNext. + + Removing from the list isn't a thread safe operation + so can't be done when other threads are running that will be using the list. + + The list does not own the factories, so removing a factory does not delete it. + */ + void Remove(); +}; + + +/** + @class wxFilterOutputStream + @wxheader{stream.h} + + A filter stream has the capability of a normal + stream but it can be placed on top of another stream. So, for example, it + can compress, encrypt the data which are passed to it and write them to another + stream. + + @library{wxbase} + @category{streams} + + @seealso + wxFilterClassFactory, wxFilterInputStream +*/ +class wxFilterOutputStream : public wxOutputStream +{ +public: + //@{ + /** + Initializes a "filter" stream. + + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxFilterOutputStream(wxOutputStream& stream); + wxFilterOutputStream(wxOutputStream* stream); + //@} +}; + + +/** + @class wxFilterInputStream + @wxheader{stream.h} + + A filter stream has the capability of a normal stream but it can be placed on + top + of another stream. So, for example, it can uncompress or decrypt the data which + are read + from another stream and pass it to the requester. + + @library{wxbase} + @category{streams} + + @seealso + wxFilterClassFactory, wxFilterOutputStream +*/ +class wxFilterInputStream : public wxInputStream +{ +public: + //@{ + /** + Initializes a "filter" stream. + + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxFilterInputStream(wxInputStream& stream); + wxFilterInputStream(wxInputStream* stream); + //@} +}; + + +/** + @class wxBufferedOutputStream + @wxheader{stream.h} + + This stream acts as a cache. It caches the bytes to be written to the specified + output stream (See wxFilterOutputStream). The + data is only written when the cache is full, when the buffered stream is + destroyed or when calling SeekO(). + + This class may not be used without some other stream to write the data + to (such as a file stream or a memory stream). + + @library{wxbase} + @category{streams} + + @seealso + wxStreamBuffer, wxOutputStream +*/ +class wxBufferedOutputStream : public wxFilterOutputStream +{ +public: + /** + Creates a buffered stream using a buffer of a default size of 1024 bytes for + cashing + the stream @e parent. + */ + wxBufferedOutputStream(const wxOutputStream& parent); + + /** + Destructor. Calls Sync() and destroys the internal buffer. + */ + ~wxBufferedOutputStream(); + + /** + Calls Sync() and changes the stream position. + */ + off_t SeekO(off_t pos, wxSeekMode mode); + + /** + Flushes the buffer and calls Sync() on the parent stream. + */ + void Sync(); +}; + + +/** + @class wxInputStream + @wxheader{stream.h} + + wxInputStream is an abstract base class which may not be used directly. + + @library{wxbase} + @category{streams} +*/ +class wxInputStream : public wxStreamBase +{ +public: + /** + Creates a dummy input stream. + */ + wxInputStream(); + + /** + Destructor. + */ + ~wxInputStream(); + + /** + Returns @true if some data is available in the stream right now, so that + calling Read() wouldn't block. + */ + bool CanRead(); + + /** + Returns @true after an attempt has been made to read past the end of the + stream. + */ +#define bool Eof() /* implementation is private */ + + /** + Returns the first character in the input queue and removes it, + blocking until it appears if necessary. + */ +#define char GetC() /* implementation is private */ + + /** + Returns the last number of bytes read. + */ + size_t LastRead(); + + /** + Returns the first character in the input queue without removing it. + */ + char Peek(); + + //@{ + /** + Reads data from the input queue and stores it in the specified output stream. + The data is read until an error is raised by one of the two streams. + + @returns This function returns a reference on the current object, so the + user can test any states of the stream right away. + */ + wxInputStream Read(void * buffer, size_t size); + Warning Return value +This function returns a reference on the current object, so the user can test +any states of the stream right away. +wxInputStream& Read(wxOutputStream& stream_out); + //@} + + /** + Changes the stream current position. + + @param pos + Offset to seek to. + + @param mode + One of wxFromStart, wxFromEnd, wxFromCurrent. + + @returns The new stream position or wxInvalidOffset on error. + */ + off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart); + + /** + Returns the current stream position. + */ + off_t TellI(); + + //@{ + /** + This function acts like the previous one except that it takes only one + character: it is sometimes shorter to use than the generic function. + */ + size_t Ungetch(const char* buffer, size_t size); + Return value bool Ungetch(char c); + //@} +}; + + +/** + @class wxStreamBase + @wxheader{stream.h} + + This class is the base class of most stream related classes in wxWidgets. It + must + not be used directly. + + @library{wxbase} + @category{streams} + + @seealso + wxStreamBuffer +*/ +class wxStreamBase +{ +public: + /** + Creates a dummy stream object. It doesn't do anything. + */ + wxStreamBase(); + + /** + Destructor. + */ + ~wxStreamBase(); + + /** + This function returns the last error. + + + @b wxSTREAM_NO_ERROR + + + No error occurred. + + @b wxSTREAM_EOF + + + An End-Of-File occurred. + + @b wxSTREAM_WRITE_ERROR + + + A generic error occurred on the last write call. + + @b wxSTREAM_READ_ERROR + + + A generic error occurred on the last read call. + */ + wxStreamError GetLastError(); + + /** + Returns the length of the stream in bytes. If the length cannot be determined + (this is always the case for socket streams for example), returns + @c wxInvalidOffset. + + This function is new since wxWidgets version 2.5.4 + */ + wxFileOffset GetLength(); + + /** + GetLength() + + This function returns the size of the stream. For example, for a file it is the + size of the file. + */ + size_t GetSize(); + + /** + Returns @true if no error occurred on the stream. + + @sa GetLastError() + */ +#define virtual bool IsOk() /* implementation is private */ + + /** + Returns @true if the streams supports seeking to arbitrary offsets. + */ + bool IsSeekable(); + + /** + Internal function. It is called when the stream wants to read data of the + specified size. It should return the size that was actually read. + */ + size_t OnSysRead(void* buffer, size_t bufsize); + + /** + Internal function. It is called when the stream needs to change the + current position. + */ + off_t OnSysSeek(off_t pos, wxSeekMode mode); + + /** + Internal function. Is is called when the stream needs to know the + real position. + */ + off_t OnSysTell(); + + /** + See OnSysRead(). + */ + size_t OnSysWrite(const void * buffer, size_t bufsize); +}; diff --git a/interface/string.h b/interface/string.h new file mode 100644 index 0000000000..bdef0d2936 --- /dev/null +++ b/interface/string.h @@ -0,0 +1,1315 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: string.h +// Purpose: documentation for wxStringBuffer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStringBuffer + @wxheader{string.h} + + This tiny class allows to conveniently access the wxString + internal buffer as a writable pointer without any risk of forgetting to restore + the string to the usable state later. + + For example, assuming you have a low-level OS function called + @c GetMeaningOfLifeAsString(char *) returning the value in the provided + buffer (which must be writable, of course) you might call it like this: + + @code + wxString theAnswer; + GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); + if ( theAnswer != "42" ) + { + wxLogError("Something is very wrong!"); + } + @endcode + + Note that the exact usage of this depends on whether on not wxUSE_STL is + enabled. If + wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, + and + if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same + buffer + wxString uses intact. In other words, relying on wxStringBuffer containing the + old + wxString data is probably not a good idea if you want to build your program in + both + with and without wxUSE_STL. + + @library{wxbase} + @category{FIXME} +*/ +class wxStringBuffer +{ +public: + /** + Constructs a writable string buffer object associated with the given string + and containing enough space for at least @e len characters. Basically, this + is equivalent to calling wxString::GetWriteBuf and + saving the result. + */ + wxStringBuffer(const wxString& str, size_t len); + + /** + Restores the string passed to the constructor to the usable state by calling + wxString::UngetWriteBuf on it. + */ + ~wxStringBuffer(); + + /** + Returns the writable pointer to a buffer of the size at least equal to the + length specified in the constructor. + */ + wxChar * operator wxChar *(); +}; + + +/** + @class wxString + @wxheader{string.h} + + wxString is a class representing a character string. Please see the + @ref overview_wxstringoverview "wxString overview" for more information about + it. + + As explained there, wxString implements most of the methods of the std::string + class. + These standard functions are not documented in this manual, please see the + STL documentation). + The behaviour of all these functions is identical to the behaviour described + there. + + You may notice that wxString sometimes has many functions which do the same + thing like, for example, wxString::Length, + wxString::Len and @c length() which all return the string + length. In all cases of such duplication the @c std::string-compatible + method (@c length() in this case, always the lowercase version) should be + used as it will ensure smoother transition to @c std::string when wxWidgets + starts using it instead of wxString. + + @library{wxbase} + @category{data} + + @stdobjects + Objects: + wxEmptyString + + @seealso + @ref overview_wxstringoverview "wxString overview", @ref overview_unicode + "Unicode overview" +*/ +class wxString +{ +public: + //@{ + /** + Initializes the string from first @e nLength characters of C string. + The default value of @c wxSTRING_MAXLEN means take all the string. + In Unicode build, @e conv's + wxMBConv::MB2WC method is called to + convert @e psz to wide string (the default converter uses current locale's + charset). It is ignored in ANSI build. + + @sa @ref overview_mbconvclasses "wxMBConv classes", @ref mbstr() + mb_str, @ref wcstr() wc_str + */ + wxString(); + wxString(const wxString& x); + wxString(wxChar ch, size_t n = 1); + wxString(const wxChar* psz, size_t nLength = wxSTRING_MAXLEN); + wxString(const unsigned char* psz, + size_t nLength = wxSTRING_MAXLEN); + wxString(const wchar_t* psz, const wxMBConv& conv, + size_t nLength = wxSTRING_MAXLEN); + wxString(const char* psz, const wxMBConv& conv = wxConvLibc, + size_t nLength = wxSTRING_MAXLEN); + //@} + + /** + String destructor. Note that this is not virtual, so wxString must not be + inherited from. + */ + ~wxString(); + + /** + Gets all the characters after the first occurrence of @e ch. + Returns the empty string if @e ch is not found. + */ + wxString AfterFirst(wxChar ch); + + /** + Gets all the characters after the last occurrence of @e ch. + Returns the whole string if @e ch is not found. + */ + wxString AfterLast(wxChar ch); + + /** + Preallocate enough space for wxString to store @e nLen characters. This function + may be used to increase speed when the string is constructed by repeated + concatenation as in + because it will avoid the need to reallocate string memory many times (in case + of long strings). Note that it does not set the maximal length of a string - it + will still expand if more than @e nLen characters are stored in it. Also, it + does not truncate the existing string (use + Truncate() for this) even if its current length is + greater than @e nLen + */ + void Alloc(size_t nLen); + + //@{ + /** + Concatenates character @e ch to this string, @e count times, returning a + reference + to it. + */ + wxString Append(const wxChar* psz); + wxString Append(wxChar ch, int count = 1); + //@} + + /** + Gets all characters before the first occurrence of @e ch. + Returns the whole string if @e ch is not found. + */ + wxString BeforeFirst(wxChar ch); + + /** + Gets all characters before the last occurrence of @e ch. + Returns the empty string if @e ch is not found. + */ + wxString BeforeLast(wxChar ch); + + /** + The MakeXXX() variants modify the string in place, while the other functions + return a new string which contains the original text converted to the upper or + lower case and leave the original string unchanged. + + MakeUpper() + + Upper() + + MakeLower() + + Lower() + */ + + + /** + Many functions in this section take a character index in the string. As with C + strings and/or arrays, the indices start from 0, so the first character of a + string is string[0]. Attempt to access a character beyond the end of the + string (which may be even 0 if the string is empty) will provoke an assert + failure in @ref overview_debuggingoverview "debug build", but no checks are + done in + release builds. + + This section also contains both implicit and explicit conversions to C style + strings. Although implicit conversion is quite convenient, it is advised to use + explicit @ref cstr() c_str method for the sake of clarity. Also + see overview for the cases where it is necessary to + use it. + + GetChar() + + GetWritableChar() + + SetChar() + + Last() + + @ref operatorbracket() "operator []" + + @ref cstr() c_str + + @ref mbstr() mb_str + + @ref wcstr() wc_str + + @ref fnstr() fn_str + + @ref operatorconstcharpt() "operator const char*" + */ + + + /** + Empties the string and frees memory occupied by it. + + See also: Empty() + */ + void Clear(); + + //@{ + /** + Case-sensitive comparison. + + Returns a positive value if the string is greater than the argument, zero if + it is equal to it or a negative value if it is less than the argument (same + semantics + as the standard @e strcmp() function). + + See also CmpNoCase(), IsSameAs(). + */ + int Cmp(const wxString& s); + int Cmp(const wxChar* psz); + //@} + + //@{ + /** + Case-insensitive comparison. + + Returns a positive value if the string is greater than the argument, zero if + it is equal to it or a negative value if it is less than the argument (same + semantics + as the standard @e strcmp() function). + + See also Cmp(), IsSameAs(). + */ + int CmpNoCase(const wxString& s); + int CmpNoCase(const wxChar* psz); + //@} + + /** + Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less. + + This is a wxWidgets 1.xx compatibility function; use Cmp() instead. + */ + int CompareTo(const wxChar* psz, caseCompare cmp = exact); + + /** + The default comparison function Cmp() is case-sensitive and + so is the default version of IsSameAs(). For case + insensitive comparisons you should use CmpNoCase() or + give a second parameter to IsSameAs. This last function is may be more + convenient if only equality of the strings matters because it returns a boolean + @true value if the strings are the same and not 0 (which is usually @false in + C) + as @c Cmp() does. + + Matches() is a poor man's regular expression matcher: + it only understands '*' and '?' metacharacters in the sense of DOS command line + interpreter. + + StartsWith() is helpful when parsing a line of + text which should start with some predefined prefix and is more efficient than + doing direct string comparison as you would also have to precalculate the + length of the prefix then. + + Cmp() + + CmpNoCase() + + IsSameAs() + + Matches() + + StartsWith() + + EndsWith() + */ + + + //@{ + /** + + */ + bool operator ==(const wxString& x, const wxString& y); + bool operator ==(const wxString& x, const wxChar* t); + bool operator !=(const wxString& x, const wxString& y); + bool operator !=(const wxString& x, const wxChar* t); + bool operator(const wxString& x, const wxString& y); + bool operator(const wxString& x, const wxChar* t); + bool operator =(const wxString& x, const wxString& y); + bool operator =(const wxString& x, const wxChar* t); + bool operator(const wxString& x, const wxString& y); + bool operator(const wxString& x, const wxChar* t); + bool operator =(const wxString& x, const wxString& y); + bool operator =(const wxString& x, const wxChar* t); + //@} + + /** + Anything may be concatenated (appended to) with a string. However, you can't + append something to a C string (including literal constants), so to do this it + should be converted to a wxString first. + + @ref operatorout() "operator " + + @ref plusequal() "operator +=" + + @ref operatorplus() "operator +" + + Append() + + Prepend() + */ + + + /** + A string may be constructed either from a C string, (some number of copies of) + a single character or a wide (UNICODE) string. For all constructors (except the + default which creates an empty string) there is also a corresponding assignment + operator. + + @ref construct() wxString + + @ref operatorassign() "operator =" + + @ref destruct() ~wxString + */ + + + /** + Returns @true if target appears anywhere in wxString; else @false. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool Contains(const wxString& str); + + /** + The string provides functions for conversion to signed and unsigned integer and + floating point numbers. All three functions take a pointer to the variable to + put the numeric value in and return @true if the @b entire string could be + converted to a number. + + ToLong() + + ToLongLong() + + ToULong() + + ToULongLong() + + ToDouble() + */ + + + /** + Makes the string empty, but doesn't free memory occupied by the string. + + See also: Clear(). + */ + void Empty(); + + /** + This function can be used to test if the string ends with the specified + @e suffix. If it does, the function will return @true and put the + beginning of the string before the suffix into @e rest string if it is not + @NULL. Otherwise, the function returns @false and doesn't + modify the @e rest. + */ + bool EndsWith(const wxString& suffix, wxString rest = @NULL); + + //@{ + /** + Searches for the given string. Returns the starting index, or @c wxNOT_FOUND if + not found. + */ + int Find(wxUniChar ch, bool fromEnd = @false); + int Find(const wxString& sub); + //@} + + //@{ + /** + Same as Find(). + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + int First(wxChar c); + int First(const wxChar* psz); + int First(const wxString& str); + //@} + + /** + This static function returns the string containing the result of calling + Printf() with the passed parameters on it. + + @sa FormatV(), Printf() + */ + static wxString Format(const wxChar format, ...); + + /** + This static function returns the string containing the result of calling + PrintfV() with the passed parameters on it. + + @sa Format(), PrintfV() + */ + static wxString FormatV(const wxChar format, va_list argptr); + + /** + Returns the number of occurrences of @e ch in the string. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + int Freq(wxChar ch); + + //@{ + /** + Converts given buffer of binary data from 8-bit string to wxString. In Unicode + build, the string is interpreted as being in ISO-8859-1 encoding. The version + without @e len parameter takes NUL-terminated data. + + This is a convenience method useful when storing binary data in wxString. + + This function is new since wxWidgets version 2.8.4 + + @sa wxString::To8BitData + */ + static wxString From8BitData(const char* buf, size_t len); + static wxString From8BitData(const char* buf); + //@} + + //@{ + /** + Converts the string or character from an ASCII, 7-bit form + to the native wxString representation. Most useful when using + a Unicode build of wxWidgets (note the use of @c char instead of @c wxChar). + Use @ref construct() "wxString constructors" if you + need to convert from another charset. + */ + static wxString FromAscii(const char* s); + static wxString FromAscii(const unsigned char* s); + static wxString FromAscii(const char* s, size_t len); + static wxString FromAscii(const unsigned char* s, size_t len); + static wxString FromAscii(char c); + //@} + + //@{ + /** + Converts C string encoded in UTF-8 to wxString. + + Note that this method assumes that @e s is a valid UTF-8 sequence and + doesn't do any validation in release builds, it's validity is only checked in + debug builds. + */ + static wxString FromUTF8(const char* s); + static wxString FromUTF8(const char* s, size_t len); + //@} + + /** + Returns the character at position @e n (read-only). + */ + wxChar GetChar(size_t n); + + /** + wxWidgets compatibility conversion. Returns a constant pointer to the data in + the string. + */ + const wxChar* GetData(); + + /** + Returns a reference to the character at position @e n. + */ + wxChar GetWritableChar(size_t n); + + /** + Returns a writable buffer of at least @e len bytes. + It returns a pointer to a new memory block, and the + existing data will not be copied. + + Call UngetWriteBuf() as soon as + possible to put the string back into a reasonable state. + + This method is deprecated, please use + wxStringBuffer or + wxStringBufferLength instead. + */ + wxChar* GetWriteBuf(size_t len); + + //@{ + /** + Same as Find(). + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + size_t Index(wxChar ch); + size_t Index(const wxChar* sz); + //@} + + /** + Returns @true if the string contains only ASCII characters. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsAscii(); + + /** + Returns @true if the string is empty. + */ + bool IsEmpty(); + + /** + Returns @true if the string is empty (same as wxString::IsEmpty). + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsNull(); + + /** + Returns @true if the string is an integer (with possible sign). + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsNumber(); + + //@{ + /** + Test whether the string is equal to the single character @e c. The test is + case-sensitive if @e caseSensitive is @true (default) or not if it is @c + @false. + + Returns @true if the string is equal to the character, @false otherwise. + + See also Cmp(), CmpNoCase() + */ + bool IsSameAs(const wxChar* psz, bool caseSensitive = @true); + bool IsSameAs(wxChar c, bool caseSensitive = @true); + //@} + + /** + Returns @true if the string is a word. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsWord(); + + //@{ + /** + Returns a reference to the last character (writable). + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + wxChar Last(); + wxChar Last(); + //@} + + /** + Returns the first @e count characters of the string. + */ + wxString Left(size_t count); + + /** + Returns the length of the string. + */ +#define size_t Len() /* implementation is private */ + + /** + Returns the length of the string (same as Len). + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + size_t Length(); + + /** + Returns this string converted to the lower case. + */ + wxString Lower(); + + /** + Same as MakeLower. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + void LowerCase(); + + /** + Converts all characters to lower case and returns the result. + */ + wxString MakeLower(); + + /** + Converts all characters to upper case and returns the result. + */ + wxString MakeUpper(); + + /** + Returns @true if the string contents matches a mask containing '*' and '?'. + */ + bool Matches(const wxString& mask); + + /** + These are "advanced" functions and they will be needed quite rarely. + Alloc() and Shrink() are only + interesting for optimization purposes. + wxStringBuffer + and wxStringBufferLength classes may be very + useful when working with some external API which requires the caller to provide + a writable buffer. + + Alloc() + + Shrink() + + wxStringBuffer + + wxStringBufferLength + */ + + + /** + Returns a substring starting at @e first, with length @e count, or the rest of + the string if @e count is the default value. + */ +#define wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) /* implementation is private */ + + /** + Other string functions. + + Trim() + + Truncate() + + Pad() + */ + + + /** + Adds @e count copies of @e pad to the beginning, or to the end of the string + (the default). + + Removes spaces from the left or from the right (default). + */ +#define wxString Pad(size_t count, wxChar pad = ' ', + bool fromRight = @true) /* implementation is private */ + + /** + Prepends @e str to this string, returning a reference to this string. + */ + wxString Prepend(const wxString& str); + + /** + Similar to the standard function @e sprintf(). Returns the number of + characters written, or an integer less than zero on error. + + Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports + Unix98-style positional parameters: + @b NB: This function will use a safe version of @e vsprintf() (usually called + @e vsnprintf()) whenever available to always allocate the buffer of correct + size. Unfortunately, this function is not available on all platforms and the + dangerous @e vsprintf() will be used then which may lead to buffer overflows. + */ + int Printf(const wxChar* pszFormat, ...); + + /** + Similar to vprintf. Returns the number of characters written, or an integer + less than zero + on error. + */ + int PrintfV(const wxChar* pszFormat, va_list argPtr); + + //@{ + /** + Removes @e len characters from the string, starting at @e pos. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + wxString Remove(size_t pos); + wxString Remove(size_t pos, size_t len); + //@} + + /** + Removes the last character. + */ + wxString RemoveLast(); + + /** + Replace first (or all) occurrences of substring with another one. + + @e replaceAll: global replace (default), or only the first occurrence. + + Returns the number of replacements made. + */ + size_t Replace(const wxString& strOld, const wxString& strNew, + bool replaceAll = @true); + + /** + Returns the last @e count characters. + */ + wxString Right(size_t count); + + /** + These functions replace the standard @e strchr() and @e strstr() + functions. + + Find() + + Replace() + */ + + + /** + Sets the character at position @e n. + */ + void SetChar(size_t n, wxChar ch); + + /** + Minimizes the string's memory. This can be useful after a call to + Alloc() if too much memory were preallocated. + */ + void Shrink(); + + /** + This function can be used to test if the string starts with the specified + @e prefix. If it does, the function will return @true and put the rest + of the string (i.e. after the prefix) into @e rest string if it is not + @NULL. Otherwise, the function returns @false and doesn't modify the + @e rest. + */ + bool StartsWith(const wxString& prefix, wxString rest = @NULL); + + /** + These functions return the string length and check whether the string is empty + or empty it. + + Len() + + IsEmpty() + + @ref operatornot() operator! + + Empty() + + Clear() + */ + + + /** + Strip characters at the front and/or end. The same as Trim except that it + doesn't change this string. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + wxString Strip(stripType s = trailing); + + /** + Returns the part of the string between the indices @e from and @e to + inclusive. + + This is a wxWidgets 1.xx compatibility function, use Mid() + instead (but note that parameters have different meaning). + */ + wxString SubString(size_t from, size_t to); + + /** + These functions allow to extract substring from this string. All of them don't + modify the original string and return a new string containing the extracted + substring. + + Mid() + + @ref operatorparenth() operator + + Left() + + Right() + + BeforeFirst() + + BeforeLast() + + AfterFirst() + + AfterLast() + + StartsWith() + + EndsWith() + */ + + + //@{ + /** + Converts the string to an 8-bit string in ISO-8859-1 encoding in the form of + a wxCharBuffer (Unicode builds only). + + This is a convenience method useful when storing binary data in wxString. + + This function is new since wxWidgets version 2.8.4 + + @sa wxString::From8BitData + */ + const char* To8BitData(); + const wxCharBuffer To8BitData(); + //@} + + //@{ + /** + Converts the string to an ASCII, 7-bit string in the form of + a wxCharBuffer (Unicode builds only) or a C string (ANSI builds). + + Note that this conversion only works if the string contains only ASCII + characters. The @ref mbstr() mb_str method provides more + powerful means of converting wxString to C string. + */ + const char* ToAscii(); + const wxCharBuffer ToAscii(); + //@} + + /** + Attempts to convert the string to a floating point number. Returns @true on + success (the number is stored in the location pointed to by @e val) or @false + if the string does not represent such number (the value of @e val is not + modified in this case). + + @sa ToLong(), ToULong() + */ + bool ToDouble(double val); + + /** + Attempts to convert the string to a signed integer in base @e base. Returns + @true on success in which case the number is stored in the location + pointed to by @e val or @false if the string does not represent a + valid number in the given base (the value of @e val is not modified + in this case). + + The value of @e base must be comprised between 2 and 36, inclusive, or + be a special value 0 which means that the usual rules of @c C numbers are + applied: if the number starts with @c 0x it is considered to be in base + 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note + that you may not want to specify the base 0 if you are parsing the numbers + which may have leading zeroes as they can yield unexpected (to the user not + familiar with C) results. + + @sa ToDouble(), ToULong() + */ + bool ToLong(long val, int base = 10); + + /** + This is exactly the same as ToLong() but works with 64 + bit integer numbers. + + Notice that currently it doesn't work (always returns @false) if parsing of 64 + bit numbers is not supported by the underlying C run-time library. Compilers + with C99 support and Microsoft Visual C++ version 7 and higher do support this. + + @sa ToLong(), ToULongLong() + */ + bool ToLongLong(wxLongLong_t val, int base = 10); + + /** + Attempts to convert the string to an unsigned integer in base @e base. + Returns @true on success in which case the number is stored in the + location pointed to by @e val or @false if the string does not + represent a valid number in the given base (the value of @e val is not + modified in this case). Please notice that this function + behaves in the same way as the standard @c strtoul() and so it simply + converts negative numbers to unsigned representation instead of rejecting them + (e.g. -1 is returned as @c ULONG_MAX). + + See ToLong() for the more detailed + description of the @e base parameter. + + @sa ToDouble(), ToLong() + */ + bool ToULong(unsigned long val, int base = 10); + + /** + This is exactly the same as ToULong() but works with 64 + bit integer numbers. + + Please see ToLongLong() for additional remarks. + */ + bool ToULongLong(wxULongLong_t val, int base = 10); + + //@{ + /** + Same as @ref wxString::utf8str utf8_str. + */ + const char* ToUTF8(); + const wxCharBuffer ToUF8(); + //@} + + /** + Removes white-space (space, tabs, form feed, newline and carriage return) from + the left or from the right end of the string (right is default). + */ + wxString Trim(bool fromRight = @true); + + /** + Truncate the string to the given length. + */ + wxString Truncate(size_t len); + + //@{ + /** + Puts the string back into a reasonable state (in which it can be used + normally), after + GetWriteBuf() was called. + + The version of the function without the @e len parameter will calculate the + new string length itself assuming that the string is terminated by the first + @c NUL character in it while the second one will use the specified length + and thus is the only version which should be used with the strings with + embedded @c NULs (it is also slightly more efficient as @c strlen() + doesn't have to be called). + + This method is deprecated, please use + wxStringBuffer or + wxStringBufferLength instead. + */ + void UngetWriteBuf(); + void UngetWriteBuf(size_t len); + //@} + + /** + Returns this string converted to upper case. + */ + wxString Upper(); + + /** + The same as MakeUpper. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + void UpperCase(); + + /** + Both formatted versions (wxString::Printf) and stream-like + insertion operators exist (for basic types only). Additionally, the + Format() function allows to use simply append + formatted value to a string: + Format() + + FormatV() + + Printf() + + PrintfV() + + @ref operatorout() "operator " + */ + + + /** + Returns a pointer to the string data (@c const char* in ANSI build, + @c const wchar_t* in Unicode build). + + Note that the returned value is not convertible to @c char* or + @c wchar_t*, use @ref charstr() char_str or + @ref wcharstr() wchar_string if you need to pass string value + to a function expecting non-const pointer. + + @sa @ref mbstr() mb_str, @ref wcstr() wc_str, @ref + fnstr() fn_str, @ref charstr() char_str, @ref + wcharstr() wchar_string + */ + const wxChar * c_str(); + + /** + Returns an object with string data that is implicitly convertible to + @c char* pointer. Note that any change to the returned buffer is lost and so + this function is only usable for passing strings to legacy libraries that + don't have const-correct API. Use wxStringBuffer if + you want to modify the string. + + @sa @ref mbstr() mb_str, @ref wcstr() wc_str, @ref + fnstr() fn_str, @ref cstr() c_str, @ref + wcharstr() wchar_str + */ + wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc); + + //@{ + /** + Returns string representation suitable for passing to OS' functions for + file handling. In ANSI build, this is same as @ref cstr() c_str. + In Unicode build, returned value can be either wide character string + or C string in charset matching the @c wxConvFileName object, depending on + the OS. + + @sa wxMBConv, @ref wcstr() wc_str, @ref wcstr() mb_str + */ + const wchar_t* fn_str(); + const char* fn_str(); + const wxCharBuffer fn_str(); + //@} + + //@{ + /** + Returns multibyte (C string) representation of the string. + In Unicode build, converts using @e conv's wxMBConv::cWC2MB + method and returns wxCharBuffer. In ANSI build, this function is same + as @ref cstr() c_str. + The macro wxWX2MBbuf is defined as the correct return type (without const). + + @sa wxMBConv, @ref cstr() c_str, @ref wcstr() wc_str, @ref + fnstr() fn_str, @ref charstr() char_str + */ + const char* mb_str(const wxMBConv& conv = wxConvLibc); + const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc); + //@} + + /** + Extraction from a stream. + */ + friend istream operator(istream& is, wxString& str); + + //@{ + /** + These functions work as C++ stream insertion operators: they insert the given + value into the string. Precision or format cannot be set using them, you can + use + Printf() for this. + */ + wxString operator(const wxString& str); + wxString operator(const wxChar* psz); + wxString operator(wxChar ch); + wxString operator(int i); + wxString operator(float f); + wxString operator(double d); + //@} + + /** + Same as Mid (substring extraction). + */ + wxString operator ()(size_t start, size_t len); + + //@{ + /** + Concatenation: all these operators return a new string equal to the + concatenation of the operands. + */ + wxString operator +(const wxString& x, const wxString& y); + wxString operator +(const wxString& x, const wxChar* y); + wxString operator +(const wxString& x, wxChar y); + wxString operator +(const wxChar* x, const wxString& y); + //@} + + //@{ + /** + Concatenation in place: the argument is appended to the string. + */ + void operator +=(const wxString& str); + void operator +=(const wxChar* psz); + void operator +=(wxChar c); + //@} + + //@{ + /** + Assignment: the effect of each operation is the same as for the corresponding + constructor (see @ref construct() "wxString constructors"). + */ + wxString operator =(const wxString& str); + wxString operator =(const wxChar* psz); + wxString operator =(wxChar c); + //@} + + //@{ + /** + Element extraction. + */ + wxChar operator [](size_t i); + wxChar operator [](size_t i); + wxChar operator [](int i); + wxChar operator [](int i); + //@} + + /** + Implicit conversion to a C string. + */ + operator const wxChar*(); + + /** + Empty string is @false, so !string will only return @true if the string is + empty. + This allows the tests for @NULLness of a @e const wxChar * pointer and emptiness + of the string to look the same in the code and makes it easier to port old code + to wxString. + + See also IsEmpty(). + */ + bool operator!(); + + /** + The supported functions are only listed here, please see any STL reference for + their documentation. + */ + + + //@{ + /** + Converts the strings contents to UTF-8 and returns it either as a temporary + wxCharBuffer object or as a pointer to the internal string contents in + UTF-8 build. + */ + const char* utf8_str(); + const wxCharBuffer utf8_str(); + //@} + + //@{ + /** + Returns wide character representation of the string. + In ANSI build, converts using @e conv's wxMBConv::cMB2WC + method and returns wxWCharBuffer. In Unicode build, this function is same + as @ref cstr() c_str. + The macro wxWX2WCbuf is defined as the correct return type (without const). + + @sa wxMBConv, @ref cstr() c_str, @ref wcstr() mb_str, @ref + fnstr() fn_str, @ref wcharstr() wchar_str + */ + const wchar_t* wc_str(const wxMBConv& conv); + const wxWCharBuffer wc_str(const wxMBConv& conv); + //@} + + /** + Returns an object with string data that is implicitly convertible to + @c char* pointer. Note that changes to the returned buffer may or may + not be lost (depending on the build) and so this function is only usable for + passing strings to legacy libraries that don't have const-correct API. Use + wxStringBuffer if you want to modify the string. + + @sa @ref mbstr() mb_str, @ref wcstr() wc_str, @ref + fnstr() fn_str, @ref cstr() c_str, @ref + charstr() char_str + */ + wxWritableWCharBuffer wchar_str(); + + /** + These functions are deprecated, please consider using new wxWidgets 2.0 + functions instead of them (or, even better, std::string compatible variants). + + CompareTo() + + Contains() + + First() + + Freq() + + Index() + + IsAscii() + + IsNull() + + IsNumber() + + IsWord() + + Last() + + Length() + + LowerCase() + + Remove() + + Strip() + + SubString() + + UpperCase() + */ +}; + + +/** + @class wxStringBufferLength + @wxheader{string.h} + + This tiny class allows to conveniently access the wxString + internal buffer as a writable pointer without any risk of forgetting to restore + the string to the usable state later, and allows the user to set the internal + length of the string. + + For example, assuming you have a low-level OS function called + @c int GetMeaningOfLifeAsString(char *) copying the value in the provided + buffer (which must be writable, of course), and returning the actual length + of the string, you might call it like this: + + @code + wxString theAnswer; + wxStringBuffer theAnswerBuffer(theAnswer, 1024); + int nLength = GetMeaningOfLifeAsString(theAnswerBuffer); + theAnswerBuffer.SetLength(nLength); + if ( theAnswer != "42" ) + { + wxLogError("Something is very wrong!"); + } + @endcode + + Note that the exact usage of this depends on whether on not wxUSE_STL is + enabled. If + wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, + and + if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same + buffer + wxString uses intact. In other words, relying on wxStringBuffer containing the + old + wxString data is probably not a good idea if you want to build your program in + both + with and without wxUSE_STL. + + Note that SetLength @c must be called before wxStringBufferLength destructs. + + @library{wxbase} + @category{FIXME} +*/ +class wxStringBufferLength +{ +public: + /** + Constructs a writable string buffer object associated with the given string + and containing enough space for at least @e len characters. Basically, this + is equivalent to calling wxString::GetWriteBuf and + saving the result. + */ + wxStringBufferLength(const wxString& str, size_t len); + + /** + Restores the string passed to the constructor to the usable state by calling + wxString::UngetWriteBuf on it. + */ + ~wxStringBufferLength(); + + /** + Sets the internal length of the string referred to by wxStringBufferLength to + @e nLength characters. + + Must be called before wxStringBufferLength destructs. + */ + void SetLength(size_t nLength); + + /** + Returns the writable pointer to a buffer of the size at least equal to the + length specified in the constructor. + */ + wxChar * operator wxChar *(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +//@{ +/** + Converts its argument to string. + See also: wxFromString. +*/ +wxString wxToString(const wxColour& col); + wxString wxToString(const wxFont& col); +//@} + +//@{ +/** + Converts string to the type of the second argument. Returns @true on success. + See also: wxToString. +*/ +bool wxFromString(const wxString& str, wxColour* col); + bool wxFromString(const wxString& str, wxFont* col); +//@} + diff --git a/interface/sysopt.h b/interface/sysopt.h new file mode 100644 index 0000000000..92065538d3 --- /dev/null +++ b/interface/sysopt.h @@ -0,0 +1,80 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sysopt.h +// Purpose: documentation for wxSystemOptions class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSystemOptions + @wxheader{sysopt.h} + + wxSystemOptions stores option/value pairs that wxWidgets itself or + applications can use to alter behaviour at run-time. It can be + used to optimize behaviour that doesn't deserve a distinct API, + but is still important to be able to configure. + + These options are currently recognised by wxWidgets. + + @library{wxbase} + @category{misc} + + @seealso + wxSystemOptions::SetOption, wxSystemOptions::GetOptionInt, + wxSystemOptions::HasOption +*/ +class wxSystemOptions : public wxObject +{ +public: + /** + Default constructor. You don't need to create an instance of wxSystemOptions + since all of its functions are static. + */ + wxSystemOptions(); + + /** + Gets an option. The function is case-insensitive to @e name. + + Returns empty string if the option hasn't been set. + + @sa SetOption(), GetOptionInt(), + HasOption() + */ + wxString GetOption(const wxString& name); + + /** + Gets an option as an integer. The function is case-insensitive to @e name. + + If the option hasn't been set, this function returns 0. + + @sa SetOption(), GetOption(), + HasOption() + */ + int GetOptionInt(const wxString& name); + + /** + Returns @true if the given option is present. The function is + case-insensitive to @e name. + + @sa SetOption(), GetOption(), + GetOptionInt() + */ + bool HasOption(const wxString& name); + + /** + Returns @true if the option with the given @e name had been set to 0 + value. This is mostly useful for boolean options for which you can't use + @c GetOptionInt(name) == 0 as this would also be @true if the option + hadn't been set at all. + */ + bool IsFalse(const wxString& name); + + //@{ + /** + Sets an option. The function is case-insensitive to @e name. + */ + void SetOption(const wxString& name, const wxString& value); + void SetOption(const wxString& name, int value); + //@} +}; diff --git a/interface/tarstrm.h b/interface/tarstrm.h new file mode 100644 index 0000000000..12ea1c363e --- /dev/null +++ b/interface/tarstrm.h @@ -0,0 +1,365 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tarstrm.h +// Purpose: documentation for wxTarInputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTarInputStream + @wxheader{tarstrm.h} + + Input stream for reading tar files. + + wxTarInputStream::GetNextEntry returns an + wxTarEntry object containing the meta-data + for the next entry in the tar (and gives away ownership). Reading from + the wxTarInputStream then returns the entry's data. Eof() becomes @true + after an attempt has been made to read past the end of the entry's data. + When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). + + Tar entries are seekable if the parent stream is seekable. In practice this + usually means they are only seekable if the tar is stored as a local file and + is not compressed. + + @library{wxbase} + @category{streams} + + @seealso + @ref overview_wxarcbyname "Looking up an archive entry by name" +*/ +class wxTarInputStream : public wxArchiveInputStream +{ +public: + //@{ + /** + Constructor. In a Unicode build the second parameter @e conv is + used to translate fields from the standard tar header into Unicode. It has + no effect on the stream's data. @e conv is only used for the standard + tar headers, any pax extended headers are always UTF-8 encoded. + + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxTarInputStream(wxInputStream& stream, + wxMBConv& conv = wxConvLocal); + wxTarInputStream(wxInputStream* stream, + wxMBConv& conv = wxConvLocal); + //@} + + /** + Closes the current entry. On a non-seekable stream reads to the end of + the current entry first. + */ + bool CloseEntry(); + + /** + Closes the current entry if one is open, then reads the meta-data for + the next entry and returns it in a wxTarEntry + object, giving away ownership. The stream is then open and can be read. + */ + wxTarEntry* GetNextEntry(); + + /** + Closes the current entry if one is open, then opens the entry specified + by the @e entry object. + + @e entry should be from the same tar file, and the tar should + be on a seekable stream. + */ + bool OpenEntry(wxTarEntry& entry); +}; + + +/** + @class wxTarClassFactory + @wxheader{tarstrm.h} + + Class factory for the tar archive format. See the base class + for details. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarc "Archive formats such as zip", @ref overview_wxarcgeneric + "Generic archive programming", wxTarEntry, wxTarInputStream, wxTarOutputStream +*/ +class wxTarClassFactory : public wxArchiveClassFactory +{ +public: + +}; + + +/** + @class wxTarOutputStream + @wxheader{tarstrm.h} + + Output stream for writing tar files. + + wxTarOutputStream::PutNextEntry is used to create + a new entry in the output tar, then the entry's data is written to the + wxTarOutputStream. Another call to PutNextEntry() closes the current + entry and begins the next. + + @library{wxbase} + @category{streams} + + @seealso + @ref overview_wxarc "Archive formats such as zip", wxTarEntry, wxTarInputStream +*/ +class wxTarOutputStream : public wxArchiveOutputStream +{ +public: + //@{ + /** + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + + In a Unicode build the third parameter @e conv is used to translate the + headers fields into an 8-bit encoding. It has no effect on the stream's data. + + When the @e format is @e wxTAR_PAX, pax extended headers are generated + when any header field will not fit the standard tar header block or if it + uses any non-ascii characters. + + Extended headers are stored as extra 'files' within the tar, and will be + extracted as such by any other tar program that does not understand them. + The @e conv parameter only affect the standard tar headers, the extended + headers are always UTF-8 encoded. + + When the @e format is @e wxTAR_USTAR, no extended headers are + generated, and instead a warning message is logged if any header field + overflows. + */ + wxTarOutputStream(wxOutputStream& stream, + wxTarFormat format = wxTAR_PAX, + wxMBConv& conv = wxConvLocal); + wxTarOutputStream(wxOutputStream* stream, + wxTarFormat format = wxTAR_PAX, + wxMBConv& conv = wxConvLocal); + //@} + + /** + The destructor calls Close() to finish + writing the tar if it has not been called already. + */ + ~wxTarOutputStream(); + + /** + Finishes writing the tar, returning @true if successful. + Called by the destructor if not called explicitly. + */ + bool Close(); + + /** + Close the current entry. It is called implicitly whenever another new + entry is created with CopyEntry() + or PutNextEntry(), or + when the tar is closed. + */ + bool CloseEntry(); + + /** + See wxArchiveOutputStream::CopyArchiveMetaData. + For the tar format this function does nothing. + */ + bool CopyArchiveMetaData(wxTarInputStream& s); + + /** + Takes ownership of @e entry and uses it to create a new entry + in the tar. @e entry is then opened in @e inputStream and its contents + copied to this stream. + + For some other archive formats CopyEntry() is much more efficient than + transferring the data using Read() and Write() since it will copy them + without decompressing and recompressing them. For tar however it makes + no difference. + + For tars on seekable streams, @e entry must be from the same tar file + as @e stream. For non-seekable streams, @e entry must also be the + last thing read from @e inputStream. + */ + bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream); + + //@{ + /** + The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes. + + Defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR + (see the @ref wxtaroutputstream() constructor), as + specified in the POSIX standards. + */ + int GetBlockingFactor(); + void SetBlockingFactor(int factor); + //@} + + /** + ) + + Create a new directory entry + (see wxArchiveEntry::IsDir) + with the given name and timestamp. + + PutNextEntry() can + also be used to create directory entries, by supplying a name with + a trailing path separator. + */ + bool PutNextDirEntry(const wxString& name); + + //@{ + /** + , @b wxFileOffset@e size = wxInvalidOffset) + + Create a new entry with the given name, timestamp and size. + */ + bool PutNextEntry(wxTarEntry* entry); + bool PutNextEntry(const wxString& name); + //@} +}; + + +/** + @class wxTarEntry + @wxheader{tarstrm.h} + + Holds the meta-data for an entry in a tar. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarc "Archive formats such as zip", wxTarInputStream, + wxTarOutputStream +*/ +class wxTarEntry : public wxArchiveEntry +{ +public: + //@{ + /** + Copy constructor. + */ + wxTarEntry(const wxString& name = wxEmptyString); + wxTarEntry(const wxTarEntry& entry); + //@} + + //@{ + /** + The entry's access time stamp. See also + wxArchiveEntry::Get/SetDateTime. + */ + wxDateTime GetAccessTime(); + void SetAccessTime(const wxDateTime& dt); + //@} + + //@{ + /** + The entry's creation time stamp. See also + wxArchiveEntry::Get/SetDateTime. + */ + wxDateTime GetCreateTime(); + void SetCreateTime(const wxDateTime& dt); + //@} + + //@{ + /** + OS specific IDs defining a device, these are only meaningful when + TypeFlag() is set to @e wxTAR_CHRTYPE + or @e wxTAR_BLKTYPE. + */ + int GetDevMajor(); + int GetDevMinor(); + void SetDevMajor(int dev); + void SetDevMinor(int dev); + //@} + + //@{ + /** + The user ID and group ID that has @ref mode() permissions over + this entry. These values aren't usually useful unless the file will only be + restored to the same system it originated from. @ref unamegname() + "Get/SetGroupName and + Get/SetUserName" can be used instead. + */ + int GetGroupId(); + int GetUserId(); + void SetGroupId(int id); + void SetUserId(int id); + //@} + + //@{ + /** + The names of the user and group that has @ref mode() permissions + over this entry. These are not present in very old tars. + */ + wxString GetGroupName(); + wxString GetUserName(); + void SetGroupName(const wxString& group); + void SetUserName(const wxString& user); + //@} + + //@{ + /** + The filename of a previous entry in the tar that this entry is a link to. + Only meaningful when TypeFlag() is set + to @e wxTAR_LNKTYPE or @e wxTAR_SYMTYPE. + */ + wxString GetLinkName(); + void SetLinkName(const wxString& link); + //@} + + //@{ + /** + UNIX permission bits for this entry. Giving read, write and execute permissions + to the file's @ref unamegname() "User and Group" and to others. + Symbols are defined for them in wx/file.h. + */ + int GetMode(); + void SetMode(int mode); + //@} + + //@{ + /** + The size of the entry's data in bytes. + + The tar archive format stores the entry's size ahead of the entry's data. + Therefore when creating an archive on a non-seekable stream it is necessary to + supply the correct size when each entry is created. For seekable streams this + is not necessary as wxTarOutputStream will attempt + to seek back and fix the entry's header when the entry is closed, though it is + still more efficient if the size is given beforehand. + */ + void SetSize(wxFileOffset size); + wxFileOffset GetSize(); + //@} + + //@{ + /** + Returns the type of the entry. It should be one of the following: + When creating archives use just these values. When reading archives + any other values should be treated as @e wxTAR_REGTYPE. + */ + int GetTypeFlag(); + void SetTypeFlag(int type); + //@} + + //@{ + /** + A static member that translates a filename into the internal format used + within the archive. If the third parameter is provided, the bool pointed + to is set to indicate whether the name looks like a directory name + (i.e. has a trailing path separator). + */ + wxString GetInternalName(); + wxString GetInternalName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE, + bool* pIsDir = @NULL); + //@} + + /** + Assignment operator. + */ + wxTarEntry& operator operator=(const wxTarEntry& entry); +}; diff --git a/interface/taskbar.h b/interface/taskbar.h new file mode 100644 index 0000000000..7d1e241340 --- /dev/null +++ b/interface/taskbar.h @@ -0,0 +1,77 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: taskbar.h +// Purpose: documentation for wxTaskBarIcon class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTaskBarIcon + @wxheader{taskbar.h} + + This class represents a taskbar icon. A taskbar icon is an icon that appears in + the 'system tray' and responds to mouse clicks, optionally with a tooltip above it to help provide information. + + @library{wxadv} + @category{FIXME} +*/ +class wxTaskBarIcon : public wxEvtHandler +{ +public: + /** + Default constructor. + */ + wxTaskBarIcon(); + + /** + Destroys the wxTaskBarIcon object, removing the icon if not already removed. + */ + ~wxTaskBarIcon(); + + /** + This method is called by the library when the user requests popup menu + (on Windows and Unix platforms, this is when the user right-clicks the icon). + Override this function in order to provide popup menu associated with the icon. + + If CreatePopupMenu returns @NULL (this happens by default), + no menu is shown, otherwise the menu is + displayed and then deleted by the library as soon as the user dismisses it. + The events can be handled by a class derived from wxTaskBarIcon. + */ + virtual wxMenu* CreatePopupMenu(); + + /** + This method is similar to wxWindow::Destroy and can + be used to schedule the task bar icon object for the delayed destruction: it + will be deleted during the next event loop iteration, which allows the task bar + icon to process any pending events for it before being destroyed. + */ + void Destroy(); + + /** + Returns @true if SetIcon() was called with no subsequent RemoveIcon(). + */ + bool IsIconInstalled(); + + /** + Returns @true if the object initialized successfully. + */ +#define bool IsOk() /* implementation is private */ + + /** + Pops up a menu at the current mouse position. The events can be handled by + a class derived from wxTaskBarIcon. + */ + bool PopupMenu(wxMenu* menu); + + /** + Removes the icon previously set with SetIcon(). + */ + bool RemoveIcon(); + + /** + Sets the icon, and optional tooltip text. + */ + bool SetIcon(const wxIcon& icon, const wxString& tooltip); +}; diff --git a/interface/textctrl.h b/interface/textctrl.h new file mode 100644 index 0000000000..ca68c4212c --- /dev/null +++ b/interface/textctrl.h @@ -0,0 +1,1430 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: textctrl.h +// Purpose: documentation for wxTextAttr class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextAttr + @wxheader{textctrl.h} + + wxTextAttr represents the character and paragraph attributes, or style, + for a range of text in a wxTextCtrl or wxRichTextCtrl. + + When setting up a wxTextAttr object, pass a bitlist mask to + wxTextAttr::SetFlags to + indicate which style elements should be changed. As a convenience, when you + call a setter such + as SetFont, the relevant bit will be set. + + @library{wxcore} + @category{richtext} + + @seealso + wxTextCtrl, wxRichTextCtrl +*/ +class wxTextAttr +{ +public: + //@{ + /** + Constructors. + */ + wxTextAttr(); + wxTextAttr(const wxColour& colText, + const wxColour& colBack = wxNullColour, + const wxFont& font = wxNullFont, + wxTextAttrAlignment alignment = wxTEXT_ALIGNMENT_DEFAULT); + wxTextAttr(const wxTextAttr& attr); + //@} + + /** + Applies the attributes in @e style to the original object, but not those + attributes from @e style that are the same as those in @e compareWith (if passed). + */ + bool Apply(const wxTextAttr& style, + const wxTextAttr* compareWith = @NULL); + + /** + Creates a font from the font attributes. + */ + wxFont CreateFont(); + + /** + Returns the alignment flags. + See SetAlignment() for a list of available styles. + */ + wxTextAttrAlignment GetAlignment(); + + /** + Returns the background colour. + */ + const wxColour GetBackgroundColour(); + + /** + Returns a string containing the name of the font associated with the bullet + symbol. + Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL. + */ + const wxString GetBulletFont(); + + /** + Returns the standard bullet name, applicable if the bullet style is + wxTEXT_ATTR_BULLET_STYLE_STANDARD. + Currently the following standard bullet names are supported: + + @c standard/circle + @c standard/square + @c standard/diamond + @c standard/triangle + + For wxRichTextCtrl users only: if you wish your rich text controls to support + further bullet graphics, you can derive a + class from wxRichTextRenderer or wxRichTextStdRenderer, override @c + DrawStandardBullet and @c EnumerateStandardBulletNames, and + set an instance of the class using wxRichTextBuffer::SetRenderer. + */ + const wxString GetBulletName(); + + /** + Returns the bullet number. + */ + int GetBulletNumber(); + + /** + Returns the bullet style. + See SetBulletStyle() for a list of available styles. + */ + int GetBulletStyle(); + + /** + Returns the bullet text, which could be a symbol, or (for example) cached + outline text. + */ + const wxString GetBulletText(); + + /** + Returns the name of the character style. + */ + const wxString GetCharacterStyleName(); + + /** + Returns flags indicating which attributes are applicable. + See SetFlags() for a list of available flags. + */ + long GetFlags(); + + /** + Creates and returns a font specified by the font attributes in the wxTextAttr + object. Note that + wxTextAttr does not store a wxFont object, so this is only a temporary font. + For greater + efficiency, access the font attributes directly. + */ + wxFont GetFont(); + + /** + Gets the font attributes from the given font, using only the attributes + specified by @e flags. + */ + bool GetFontAttributes(const wxFont& font, + int flags = wxTEXT_ATTR_FONT); + + /** + Returns the font encoding. + */ + wxFontEncoding GetFontEncoding(); + + /** + Returns the font face name. + */ + const wxString GetFontFaceName(); + + /** + Returns the font size in points. + */ + int GetFontSize(); + + /** + Returns the font style. + */ + int GetFontStyle(); + + /** + Returns @true if the font is underlined. + */ + bool GetFontUnderlined(); + + /** + Returns the font weight. + */ + int GetFontWeight(); + + /** + Returns the left indent in tenths of a millimetre. + */ + long GetLeftIndent(); + + /** + Returns the left sub-indent in tenths of a millimetre. + */ + long GetLeftSubIndent(); + + /** + Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL, + wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE. + */ + int GetLineSpacing(); + + /** + Returns the name of the list style. + */ + const wxString GetListStyleName(); + + /** + Returns the outline level. + */ + bool GetOutlineLevel(); + + /** + Returns the space in tenths of a millimeter after the paragraph. + */ + int GetParagraphSpacingAfter(); + + /** + Returns the space in tenths of a millimeter before the paragraph. + */ + int GetParagraphSpacingBefore(); + + /** + Returns the name of the paragraph style. + */ + const wxString GetParagraphStyleName(); + + /** + Returns the right indent in tenths of a millimeter. + */ + long GetRightIndent(); + + /** + Returns an array of tab stops, each expressed in tenths of a millimeter. Each + stop + is measured from the left margin and therefore each value must be larger than + the last. + */ + const wxArrayInt GetTabs(); + + /** + Returns the text foreground colour. + */ + const wxColour GetTextColour(); + + /** + Returns the text effect bits of interest. See SetFlags() for further + information. + */ + int GetTextEffectFlags(); + + /** + Returns the text effects, a bit list of styles. See SetTextEffects() for + details. + */ + int GetTextEffects(); + + /** + Returns the URL for the content. Content with wxTEXT_ATTR_URL style + causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl + generates + a wxTextUrlEvent when the content is clicked. + */ +#define const wxString GetURL() /* implementation is private */ + + /** + Returns @true if the attribute object specifies alignment. + */ + bool HasAlignment(); + + /** + Returns @true if the attribute object specifies a background colour. + */ + bool HasBackgroundColour(); + + /** + Returns @true if the attribute object specifies a standard bullet name. + */ + bool HasBulletName(); + + /** + Returns @true if the attribute object specifies a bullet number. + */ + bool HasBulletNumber(); + + /** + Returns @true if the attribute object specifies a bullet style. + */ + bool HasBulletStyle(); + + /** + Returns @true if the attribute object specifies bullet text (usually + specifying a symbol). + */ + bool HasBulletText(); + + /** + Returns @true if the attribute object specifies a character style name. + */ + bool HasCharacterStyleName(); + + /** + Returns @true if the @e flag is present in the attribute object's flag + bitlist. + */ + bool HasFlag(long flag); + + /** + Returns @true if the attribute object specifies any font attributes. + */ + bool HasFont(); + + /** + Returns @true if the attribute object specifies an encoding. + */ + bool HasFontEncoding(); + + /** + Returns @true if the attribute object specifies a font face name. + */ + bool HasFontFaceName(); + + /** + Returns @true if the attribute object specifies italic style. + */ + bool HasFontItalic(); + + /** + Returns @true if the attribute object specifies a font point size. + */ + bool HasFontSize(); + + /** + Returns @true if the attribute object specifies either underlining or no + underlining. + */ + bool HasFontUnderlined(); + + /** + Returns @true if the attribute object specifies font weight (bold, light or + normal). + */ + bool HasFontWeight(); + + /** + Returns @true if the attribute object specifies a left indent. + */ + bool HasLeftIndent(); + + /** + Returns @true if the attribute object specifies line spacing. + */ + bool HasLineSpacing(); + + /** + Returns @true if the attribute object specifies a list style name. + */ + bool HasListStyleName(); + + /** + Returns @true if the attribute object specifies an outline level. + */ + bool HasOutlineLevel(); + + /** + Returns @true if the attribute object specifies a page break before this + paragraph. + */ + bool HasPageBreak(); + + /** + Returns @true if the attribute object specifies spacing after a paragraph. + */ + bool HasParagraphSpacingAfter(); + + /** + Returns @true if the attribute object specifies spacing before a paragraph. + */ + bool HasParagraphSpacingBefore(); + + /** + Returns @true if the attribute object specifies a paragraph style name. + */ + bool HasParagraphStyleName(); + + /** + Returns @true if the attribute object specifies a right indent. + */ + bool HasRightIndent(); + + /** + Returns @true if the attribute object specifies tab stops. + */ + bool HasTabs(); + + /** + Returns @true if the attribute object specifies a text foreground colour. + */ + bool HasTextColour(); + + /** + Returns @true if the attribute object specifies text effects. + */ + bool HasTextEffects(); + + /** + Returns @true if the attribute object specifies a URL. + */ +#define bool HasURL() /* implementation is private */ + + /** + Returns @true if the object represents a character style, that is, + the flags specify a font or a text background or foreground colour. + */ + bool IsCharacterStyle(); + + /** + Returns @false if we have any attributes set, @true otherwise. + */ + bool IsDefault(); + + /** + Returns @true if the object represents a paragraph style, that is, + the flags specify alignment, indentation, tabs, paragraph spacing, or + bullet style. + */ + bool IsParagraphStyle(); + + //@{ + /** + Creates a new @c wxTextAttr which is a merge of @e base and + @e overlay. Properties defined in @e overlay take precedence over those + in @e base. Properties undefined/invalid in both are undefined in the + result. + */ + void Merge(const wxTextAttr& overlay); + static wxTextAttr Merge(const wxTextAttr& base, + const wxTextAttr& overlay); + //@} + + /** + Sets the paragraph alignment. These are the possible values for @e alignment: + + + Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification + may be supported + when printing or previewing, only. + */ + void SetAlignment(wxTextAttrAlignment alignment); + + /** + Sets the background colour. + */ + void SetBackgroundColour(const wxColour& colBack); + + /** + Sets the name of the font associated with the bullet symbol. + Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL. + */ + void SetBulletFont(const wxString& font); + + /** + Sets the standard bullet name, applicable if the bullet style is + wxTEXT_ATTR_BULLET_STYLE_STANDARD. + See GetBulletName() for a list + of supported names, and how to expand the range of supported types. + */ + void SetBulletName(const wxString& name); + + /** + Sets the bullet number. + */ + void SetBulletNumber(int n); + + /** + Sets the bullet style. The following styles can be passed: + + + Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported. + */ + void SetBulletStyle(int style); + + /** + Sets the bullet text, which could be a symbol, or (for example) cached outline + text. + */ + void SetBulletText(const wxString text); + + /** + Sets the character style name. + */ + void SetCharacterStyleName(const wxString& name); + + /** + Sets the flags determining which styles are being specified. The following + flags can be passed in a bitlist: + */ + void SetFlags(long flags); + + /** + Sets the attributes for the given font. Note that wxTextAttr does not store an + actual wxFont object. + */ + void SetFont(const wxFont& font); + + /** + Sets the font encoding. + */ + void SetFontEncoding(wxFontEncoding encoding); + + /** + Sets the paragraph alignment. + */ + void SetFontFaceName(const wxString& faceName); + + /** + Sets the font size in points. + */ + void SetFontSize(int pointSize); + + /** + Sets the font style (normal, italic or slanted). + */ + void SetFontStyle(int fontStyle); + + /** + Sets the font underlining. + */ + void SetFontUnderlined(bool underlined); + + /** + Sets the font weight. + */ + void SetFontWeight(int fontWeight); + + /** + Sets the left indent and left subindent in tenths of a millimetre. + + The sub-indent is an offset from the left of the paragraph, and is used for all + but the + first line in a paragraph. A positive value will cause the first line to appear + to the left + of the subsequent lines, and a negative value will cause the first line to be + indented + relative to the subsequent lines. + + wxRichTextBuffer uses indentation to render a bulleted item. The left indent is + the distance between + the margin and the bullet. The content of the paragraph, including the first + line, starts + at leftMargin + leftSubIndent. So the distance between the left edge of the + bullet and the + left of the actual paragraph is leftSubIndent. + */ + void SetLeftIndent(int indent, int subIndent = 0); + + /** + Sets the line spacing. @e spacing is a multiple, where 10 means single-spacing, + 15 means 1.5 spacing, and 20 means double spacing. The following constants are + defined for convenience: + */ + void SetLineSpacing(int spacing); + + /** + Sets the list style name. + */ + void SetListStyleName(const wxString& name); + + /** + Specifies the outline level. Zero represents normal text. At present, the + outline level is + not used, but may be used in future for determining list levels and for + applications + that need to store document structure information. + */ + void SetOutlineLevel(int level); + + /** + Specifies a page break before this paragraph. + */ + void SetPageBreak(bool pageBreak = @true); + + /** + Sets the spacing after a paragraph, in tenths of a millimetre. + */ + void SetParagraphSpacingAfter(int spacing); + + /** + Sets the spacing before a paragraph, in tenths of a millimetre. + */ + void SetParagraphSpacingBefore(int spacing); + + /** + Sets the name of the paragraph style. + */ + void SetParagraphStyleName(const wxString& name); + + /** + Sets the right indent in tenths of a millimetre. + */ + void SetRightIndent(int indent); + + /** + Sets the tab stops, expressed in tenths of a millimetre. + Each stop is measured from the left margin and therefore each value must be + larger than the last. + */ + void SetTabs(const wxArrayInt& tabs); + + /** + Sets the text foreground colout. + */ + void SetTextColour(const wxColour& colText); + + /** + Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS + to SetFlags(). + See SetFlags() for further information. + */ + void SetTextEffectFlags(int flags); + + /** + Sets the text effects, a bit list of styles. + + The following styles can be passed: + + + Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH + are implemented. + wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case + of the actual buffer + text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text. + + To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call + SetTextEffectFlags() with the styles (taken from the + above set) that you are interested in setting. + */ + void SetTextEffects(int effects); + + /** + Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this + style + causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl + generates + a wxTextUrlEvent when the content is clicked. + */ +#define void SetURL(const wxString& url) /* implementation is private */ + + /** + Assignment from a wxTextAttr object. + */ + void operator operator=(const wxTextAttr& attr); +}; + + +/** + @class wxTextCtrl + @wxheader{textctrl.h} + + A text control allows text to be displayed and edited. It may be + single line or multi-line. + + @beginStyleTable + @style{wxTE_PROCESS_ENTER}: + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). + @style{wxTE_PROCESS_TAB}: + The control will receive wxEVT_CHAR events for TAB pressed - + normally, TAB is used for passing to the next control in a dialog + instead. For the control created with this style, you can still use + Ctrl-Enter to pass to the next control from the keyboard. + @style{wxTE_MULTILINE}: + The text control allows multiple lines. + @style{wxTE_PASSWORD}: + The text will be echoed as asterisks. + @style{wxTE_READONLY}: + The text will not be user-editable. + @style{wxTE_RICH}: + Use rich text control under Win32, this allows to have more than + 64KB of text in the control even under Win9x. This style is ignored + under other platforms. + @style{wxTE_RICH2}: + Use rich text control version 2.0 or 3.0 under Win32, this style is + ignored under other platforms + @style{wxTE_AUTO_URL}: + Highlight the URLs and generate the wxTextUrlEvents when mouse + events occur over them. This style is only supported for wxTE_RICH + Win32 and multi-line wxGTK2 text controls. + @style{wxTE_NOHIDESEL}: + By default, the Windows text control doesn't show the selection + when it doesn't have focus - use this style to force it to always + show it. It doesn't do anything under other platforms. + @style{wxHSCROLL}: + A horizontal scrollbar will be created and used, so that text won't + be wrapped. No effect under wxGTK1. + @style{wxTE_NO_VSCROLL}: + For multiline controls only: vertical scrollbar will never be + created. This limits the amount of text which can be entered into + the control to what can be displayed in it under MSW but not under + GTK2. Currently not implemented for the other platforms. + @style{wxTE_LEFT}: + The text in the control will be left-justified (default). + @style{wxTE_CENTRE}: + The text in the control will be centered (currently wxMSW and + wxGTK2 only). + @style{wxTE_RIGHT}: + The text in the control will be right-justified (currently wxMSW + and wxGTK2 only). + @style{wxTE_DONTWRAP}: + Same as wxHSCROLL style: don't wrap at all, show horizontal + scrollbar instead. + @style{wxTE_CHARWRAP}: + Wrap the lines too long to be shown entirely at any position + (wxUniv and wxGTK2 only). + @style{wxTE_WORDWRAP}: + Wrap the lines too long to be shown entirely at word boundaries + (wxUniv and wxGTK2 only). + @style{wxTE_BESTWRAP}: + Wrap the lines at word boundaries or at any other character if + there are words longer than the window width (this is the default). + @style{wxTE_CAPITALIZE}: + On PocketPC and Smartphone, causes the first letter to be + capitalized. + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{textctrl.png} + + @seealso + wxTextCtrl::Create, wxValidator +*/ +class wxTextCtrl : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a text control. + + @param parent + Parent window. Should not be @NULL. + + @param id + Control identifier. A value of -1 denotes a default value. + + @param value + Default text value. + + @param pos + Text control position. + + @param size + Text control size. + + @param style + Window style. See wxTextCtrl. + + @param validator + Window validator. + + @param name + Window name. + + @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be + created for multi-line text controls. Without a + horizontal scrollbar, text lines that don't fit in + the control's size will be wrapped (but no newline + character is inserted). Single line controls don't + have a horizontal scrollbar, the text is + automatically scrolled so that the insertion point is + always visible. + + @sa Create(), wxValidator + */ + wxTextCtrl(); + wxTextCtrl(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxTextCtrlNameStr); + //@} + + /** + Destructor, destroying the text control. + */ + ~wxTextCtrl(); + + /** + Appends the text to the end of the text control. + + @param text + Text to write to the text control. + + @remarks After the text is appended, the insertion point will be at the + end of the text control. If this behaviour is not + desired, the programmer should use GetInsertionPoint + and SetInsertionPoint. + + @sa WriteText() + */ + void AppendText(const wxString& text); + + /** + Call this function to enable auto-completion of the text typed in a single-line + text control using the given @e choices. + + Notice that currently this function is only implemented in wxGTK2 and wxMSW + ports and does nothing under the other platforms. + + This function is new since wxWidgets version 2.9.0 + + @returns @true if the auto-completion was enabled or @false if the + operation failed, typically because auto-completion + is not supported by the current platform. + + @sa AutoCompleteFileNames() + */ + bool AutoComplete(const wxArrayString& choices); + + /** + Call this function to enable auto-completion of the text typed in a single-line + text control using all valid file system paths. + + Notice that currently this function is only implemented in wxGTK2 port and does + nothing under the other platforms. + + This function is new since wxWidgets version 2.9.0 + + @returns @true if the auto-completion was enabled or @false if the + operation failed, typically because auto-completion + is not supported by the current platform. + + @sa AutoComplete() + */ + bool AutoCompleteFileNames(); + + /** + Returns @true if the selection can be copied to the clipboard. + */ + virtual bool CanCopy(); + + /** + Returns @true if the selection can be cut to the clipboard. + */ + virtual bool CanCut(); + + /** + Returns @true if the contents of the clipboard can be pasted into the + text control. On some platforms (Motif, GTK) this is an approximation + and returns @true if the control is editable, @false otherwise. + */ + virtual bool CanPaste(); + + /** + Returns @true if there is a redo facility available and the last operation + can be redone. + */ + virtual bool CanRedo(); + + /** + Returns @true if there is an undo facility available and the last operation + can be undone. + */ + virtual bool CanUndo(); + + /** + Sets the text value and marks the control as not-modified (which means that + IsModified() would return @false immediately + after the call to SetValue). + + Note that this function will not generate the @c wxEVT_COMMAND_TEXT_UPDATED + event. + This is the only difference with SetValue(). + See @ref overview_progevent "this topic" for more information. + + This function is new since wxWidgets version 2.7.1 + + @param value + The new value to set. It may contain newline characters if the text control is + multi-line. + */ + virtual void ChangeValue(const wxString& value); + + /** + Clears the text in the control. + + Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED + event. + */ + virtual void Clear(); + + /** + Copies the selected text to the clipboard under Motif and MS Windows. + */ + virtual void Copy(); + + /** + Creates the text control for two-step construction. Derived classes + should call or replace this function. See wxTextCtrl() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxTextCtrlNameStr); + + /** + Copies the selected text to the clipboard and removes the selection. + */ +#define virtual void Cut() /* implementation is private */ + + /** + Resets the internal 'modified' flag as if the current edits had been saved. + */ + void DiscardEdits(); + + /** + This functions inserts into the control the character which would have been + inserted if the given key event had occurred in the text control. The + @e event object should be the same as the one passed to @c EVT_KEY_DOWN + handler previously by wxWidgets. + + Please note that this function doesn't currently work correctly for all keys + under any platform but MSW. + + @returns @true if the event resulted in a change to the control, @false + otherwise. + */ + bool EmulateKeyPress(const wxKeyEvent& event); + + /** + Returns the style currently used for the new text. + + @sa SetDefaultStyle() + */ + const wxTextAttr GetDefaultStyle(); + + /** + Returns the insertion point. This is defined as the zero based index of the + character position to the right of the insertion point. For example, if + the insertion point is at the end of the text control, it is equal to + both GetValue().Length() and + GetLastPosition(). + + The following code snippet safely returns the character at the insertion + point or the zero character if the point is at the end of the control. + */ + virtual long GetInsertionPoint(); + + /** + Returns the zero based index of the last position in the text control, + which is equal to the number of characters in the control. + */ + virtual wxTextPos GetLastPosition(); + + /** + Gets the length of the specified line, not including any trailing newline + character(s). + + @param lineNo + Line number (starting from zero). + + @returns The length of the line, or -1 if lineNo was invalid. + */ + int GetLineLength(long lineNo); + + /** + Returns the contents of a given line in the text control, not including + any trailing newline character(s). + + @param lineNo + The line number, starting from zero. + + @returns The contents of the line. + */ + wxString GetLineText(long lineNo); + + /** + Returns the number of lines in the text control buffer. + + @remarks Note that even empty text controls have one line (where the + insertion point is), so GetNumberOfLines() never + returns 0. + */ + int GetNumberOfLines(); + + /** + Returns the string containing the text starting in the positions @e from and + up to @e to in the control. The positions must have been returned by another + wxTextCtrl method. + + Please note that the positions in a multiline wxTextCtrl do @b not + correspond to the indices in the string returned by + GetValue() because of the different new line + representations (@c CR or @c CR LF) and so this method should be used to + obtain the correct results instead of extracting parts of the entire value. It + may also be more efficient, especially if the control contains a lot of data. + */ + virtual wxString GetRange(long from, long to); + + /** + Gets the current selection span. If the returned values are equal, there was + no selection. + + Please note that the indices returned may be used with the other wxTextctrl + methods but don't necessarily represent the correct indices into the string + returned by GetValue() for multiline controls + under Windows (at least,) you should use + GetStringSelection() to get the selected + text. + + @param from + The returned first position. + + @param to + The returned last position. + */ + virtual void GetSelection(long* from, long* to); + + /** + Gets the text currently selected in the control. If there is no selection, the + returned string is empty. + */ + virtual wxString GetStringSelection(); + + /** + Returns the style at this position in the text control. Not all platforms + support this function. + + @returns @true on success, @false if an error occurred - it may also mean + that the styles are not supported under this platform. + + @sa SetStyle(), wxTextAttr + */ + bool GetStyle(long position, wxTextAttr& style); + + /** + Gets the contents of the control. Notice that for a multiline text control, + the lines will be separated by (Unix-style) \n characters, even + under Windows where they are separated by a \r\n + sequence in the native control. + */ + wxString GetValue(); + + /** + This function finds the character at the specified position expressed in + pixels. If the return code is not @c wxTE_HT_UNKNOWN the row and column + of the character closest to this position are returned in the @e col and + @e row parameters (unless the pointers are @NULL which is allowed). + + Please note that this function is currently only implemented in wxUniv, + wxMSW and wxGTK2 ports. + + @sa PositionToXY(), XYToPosition() + */ + wxTextCtrlHitTestResult HitTest(const wxPoint& pt, + wxTextCoord col, + wxTextCoord row); + + /** + Returns @true if the controls contents may be edited by user (note that it + always can be changed by the program), i.e. if the control hasn't been put in + read-only mode by a previous call to + SetEditable(). + */ + bool IsEditable(); + + /** + Returns @true if the control is currently empty. This is the same as + @c GetValue().empty() but can be much more efficient for the multiline + controls containing big amounts of text. + + This function is new since wxWidgets version 2.7.1 + */ + bool IsEmpty(); + + /** + Returns @true if the text has been modified by user. Note that calling + SetValue() doesn't make the control modified. + + @sa MarkDirty() + */ + bool IsModified(); + + /** + Returns @true if this is a multi line edit control and @false + otherwise. + + @sa IsSingleLine() + */ + bool IsMultiLine(); + + /** + Returns @true if this is a single line edit control and @false + otherwise. + + @sa @ref issingleline() IsMultiLine + */ + bool IsSingleLine(); + + /** + Loads and displays the named file, if it exists. + + @param filename + The filename of the file to load. + + @param fileType + The type of file to load. This is currently ignored in wxTextCtrl. + + @returns @true if successful, @false otherwise. + */ + bool LoadFile(const wxString& filename, + int fileType = wxTEXT_TYPE_ANY); + + /** + Mark text as modified (dirty). + + @sa IsModified() + */ + void MarkDirty(); + + /** + This event handler function implements default drag and drop behaviour, which + is to load the first dropped file into the control. + + @param event + The drop files event. + + @remarks This is not implemented on non-Windows platforms. + + @sa wxDropFilesEvent + */ + void OnDropFiles(wxDropFilesEvent& event); + + /** + Pastes text from the clipboard to the text item. + */ + virtual void Paste(); + + /** + Converts given position to a zero-based column, line number pair. + + @param pos + Position. + + @param x + Receives zero based column number. + + @param y + Receives zero based line number. + + @returns @true on success, @false on failure (most likely due to a too + large position parameter). + + @sa XYToPosition() + */ + bool PositionToXY(long pos, long * x, long * y); + + /** + If there is a redo facility and the last operation can be redone, redoes the + last operation. Does nothing + if there is no redo facility. + */ + virtual void Redo(); + + /** + Removes the text starting at the first given position up to (but not including) + the character at the last position. + + @param from + The first position. + + @param to + The last position. + */ + virtual void Remove(long from, long to); + + /** + Replaces the text starting at the first position up to (but not including) + the character at the last position with the given text. + + @param from + The first position. + + @param to + The last position. + + @param value + The value to replace the existing text with. + */ + virtual void Replace(long from, long to, const wxString& value); + + /** + Saves the contents of the control in a text file. + + @param filename + The name of the file in which to save the text. + + @param fileType + The type of file to save. This is currently ignored in wxTextCtrl. + + @returns @true if the operation was successful, @false otherwise. + */ + bool SaveFile(const wxString& filename, + int fileType = wxTEXT_TYPE_ANY); + + /** + Changes the default style to use for the new text which is going to be added + to the control using WriteText() or + AppendText(). + + If either of the font, foreground, or background colour is not set in + @e style, the values of the previous default style are used for them. If + the previous default style didn't set them neither, the global font or colours + of the text control itself are used as fall back. + + However if the @e style parameter is the default wxTextAttr, then the + default style is just reset (instead of being combined with the new style which + wouldn't change it at all). + + @param style + The style for the new text. + + @returns @true on success, @false if an error occurred - may also mean that + the styles are not supported under this platform. + + @sa GetDefaultStyle() + */ + bool SetDefaultStyle(const wxTextAttr& style); + + /** + Makes the text item editable or read-only, overriding the @b wxTE_READONLY flag. + + @param editable + If @true, the control is editable. If @false, the control is read-only. + + @sa IsEditable() + */ + virtual void SetEditable(const bool editable); + + /** + Sets the insertion point at the given position. + + @param pos + Position to set. + */ + virtual void SetInsertionPoint(long pos); + + /** + Sets the insertion point at the end of the text control. This is equivalent + to wxTextCtrl::SetInsertionPoint(wxTextCtrl::GetLastPosition()). + */ + virtual void SetInsertionPointEnd(); + + /** + This function sets the maximum number of characters the user can enter into the + control. In other words, it allows to limit the text value length to @e len + not counting the terminating @c NUL character. + + If @e len is 0, the previously set max length limit, if any, is discarded + and the user may enter as much text as the underlying native text control + widget supports (typically at least 32Kb). + + If the user tries to enter more characters into the text control when it + already is filled up to the maximal length, a + @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify the program about it + (giving it the possibility to show an explanatory message, for example) and the + extra input is discarded. + + Note that under GTK+, this function may only be used with single line text + controls. + */ + virtual void SetMaxLength(unsigned long len); + + /** + Marks the control as being modified by the user or not. + + @sa MarkDirty(), DiscardEdits() + */ + void SetModified(bool modified); + + /** + Selects the text starting at the first position up to (but not including) the + character at the last position. If both parameters are equal to -1 all text + in the control is selected. + + @param from + The first position. + + @param to + The last position. + */ + virtual void SetSelection(long from, long to); + + /** + Changes the style of the given range. If any attribute within @e style is + not set, the corresponding attribute from GetDefaultStyle() is used. + + @param start + The start of the range to change. + + @param end + The end of the range to change. + + @param style + The new style for the range. + + @returns @true on success, @false if an error occurred - it may also mean + that the styles are not supported under this platform. + + @sa GetStyle(), wxTextAttr + */ + bool SetStyle(long start, long end, const wxTextAttr& style); + + /** + Sets the text value and marks the control as not-modified (which means that + IsModified() would return @false immediately + after the call to SetValue). + + Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED + event. + + This function is deprecated and should not be used in new code. Please use the + ChangeValue() function instead. + + @param value + The new value to set. It may contain newline characters if the text control is + multi-line. + */ + virtual void SetValue(const wxString& value); + + /** + Makes the line containing the given position visible. + + @param pos + The position that should be visible. + */ + void ShowPosition(long pos); + + /** + If there is an undo facility and the last operation can be undone, undoes the + last operation. Does nothing + if there is no undo facility. + */ + virtual void Undo(); + + /** + Writes the text into the text control at the current insertion position. + + @param text + Text to write to the text control. + + @remarks Newlines in the text string are the only control characters + allowed, and they will cause appropriate line breaks. + See () and AppendText() for more + convenient ways of writing to the window. + */ + void WriteText(const wxString& text); + + /** + Converts the given zero based column and line number to a position. + + @param x + The column number. + + @param y + The line number. + + @returns The position value, or -1 if x or y was invalid. + */ + long XYToPosition(long x, long y); + + //@{ + /** + Operator definitions for appending to a text control, for example: + */ + wxTextCtrl operator(const wxString& s); + wxTextCtrl operator(int i); + wxTextCtrl operator(long i); + wxTextCtrl operator(float f); + wxTextCtrl operator(double d); + wxTextCtrl operator(char c); + //@} +}; + + +/** + @class wxStreamToTextRedirector + @wxheader{textctrl.h} + + This class can be used to (temporarily) redirect all output sent to a C++ + ostream object to a wxTextCtrl instead. + + @b NB: Some compilers and/or build configurations don't support multiply + inheriting wxTextCtrl from @c std::streambuf in which + case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM + option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix, + specify @c --enable-std_iostreams switch when running configure for this. + + Example of usage: + + @code + using namespace std; + + wxTextCtrl *text = new wxTextCtrl(...); + + { + wxStreamToTextRedirector redirect(text); + + // this goes to the text control + cout "Hello, text!" endl; + } + + // this goes somewhere else, presumably to stdout + cout "Hello, console!" endl; + @endcode + + + @library{wxcore} + @category{logging} + + @seealso + wxTextCtrl +*/ +class wxStreamToTextRedirector +{ +public: + /** + The constructor starts redirecting output sent to @e ostr or @e cout for + the default parameter value to the text control @e text. + + @param text + The text control to append output too, must be non-@NULL + + @param ostr + The C++ stream to redirect, cout is used if it is @NULL + */ + wxStreamToTextRedirector(wxTextCtrl text, ostream * ostr = @NULL); + + /** + When a wxStreamToTextRedirector object is destroyed, the redirection is ended + and any output sent to the C++ ostream which had been specified at the time of + the object construction will go to its original destination. + */ + ~wxStreamToTextRedirector(); +}; diff --git a/interface/textdlg.h b/interface/textdlg.h new file mode 100644 index 0000000000..1b50a8b5cb --- /dev/null +++ b/interface/textdlg.h @@ -0,0 +1,130 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: textdlg.h +// Purpose: documentation for wxPasswordEntryDialog class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPasswordEntryDialog + @wxheader{textdlg.h} + + This class represents a dialog that requests a one-line password string from + the user. + It is implemented as a generic wxWidgets dialog. + + @library{wxbase} + @category{cmndlg} + + @seealso + @ref overview_wxpasswordentrydialogoverview "wxPassowrdEntryDialog overview" +*/ +class wxPasswordEntryDialog : public wxTextEntryDialog +{ +public: + +}; + + +/** + @class wxTextEntryDialog + @wxheader{textdlg.h} + + This class represents a dialog that requests a one-line text string from the + user. + It is implemented as a generic wxWidgets dialog. + + @library{wxbase} + @category{cmndlg} + + @seealso + @ref overview_wxtextentrydialogoverview "wxTextEntryDialog overview" +*/ +class wxTextEntryDialog : public wxDialog +{ +public: + /** + Constructor. Use ShowModal() to show the dialog. + + @param parent + Parent window. + + @param message + Message to show on the dialog. + + @param defaultValue + The default value, which may be the empty string. + + @param style + A dialog style, specifying the buttons (wxOK, wxCANCEL) + and an optional wxCENTRE style. Additionally, wxTextCtrl styles (such as + wxTE_PASSWORD) may be specified here. + + @param pos + Dialog position. + */ + wxTextEntryDialog(wxWindow* parent, const wxString& message, + const wxString& caption = "Please enter text", + const wxString& defaultValue = "", + long style = wxOK | wxCANCEL | wxCENTRE, + const wxPoint& pos = wxDefaultPosition); + + /** + Destructor. + */ + ~wxTextEntryDialog(); + + /** + Returns the text that the user has entered if the user has pressed OK, or the + original value + if the user has pressed Cancel. + */ + wxString GetValue(); + + /** + Sets the default text value. + */ + void SetValue(const wxString& value); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL + otherwise. + */ + int ShowModal(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Pop up a dialog box with title set to @e caption, @e message, and a + @e default_value. The user may type in text and press OK to return this text, + or press Cancel to return the empty string. + + If @e centre is @true, the message text (which may include new line characters) + is centred; if @false, the message is left-justified. +*/ +wxString wxGetTextFromUser(const wxString& message, + const wxString& caption = "Input text", + const wxString& default_value = "", + wxWindow * parent = @NULL, + int x = wxDefaultCoord, + int y = wxDefaultCoord, + bool centre = @true); + +/** + Similar to wxGetTextFromUser but the text entered + in the dialog is not shown on screen but replaced with stars. This is intended + to be used for entering passwords as the function name implies. +*/ +wxString wxGetPasswordFromUser(const wxString& message, + const wxString& caption = "Input text", + const wxString& default_value = "", + wxWindow * parent = @NULL, + int x = wxDefaultCoord, + int y = wxDefaultCoord, + bool centre = @true); + diff --git a/interface/textfile.h b/interface/textfile.h new file mode 100644 index 0000000000..69ef38f9dd --- /dev/null +++ b/interface/textfile.h @@ -0,0 +1,247 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: textfile.h +// Purpose: documentation for wxTextFile class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextFile + @wxheader{textfile.h} + + The wxTextFile is a simple class which allows to work with text files on line by + line basis. It also understands the differences in line termination characters + under different platforms and will not do anything bad to files with "non + native" line termination sequences - in fact, it can be also used to modify the + text files and change the line termination characters from one type (say DOS) to + another (say Unix). + + One word of warning: the class is not at all optimized for big files and thus + it will load the file entirely into memory when opened. Of course, you should + not + work in this way with large files (as an estimation, anything over 1 Megabyte is + surely too big for this class). On the other hand, it is not a serious + limitation for small files like configuration files or program sources + which are well handled by wxTextFile. + + The typical things you may do with wxTextFile in order are: + + Create and open it: this is done with either + wxTextFile::Create or wxTextFile::Open + function which opens the file (name may be specified either as the argument to + these functions or in the constructor), reads its contents in memory (in the + case of @c Open()) and closes it. + Work with the lines in the file: this may be done either with "direct + access" functions like wxTextFile::GetLineCount and + wxTextFile::GetLine (@e operator[] does exactly the same + but looks more like array addressing) or with "sequential access" functions + which include wxTextFile::GetFirstLine/ + wxTextFile::GetNextLine and also + wxTextFile::GetLastLine/wxTextFile::GetPrevLine. + For the sequential access functions the current line number is maintained: it is + returned by wxTextFile::GetCurrentLine and may be + changed with wxTextFile::GoToLine. + Add/remove lines to the file: wxTextFile::AddLine and + wxTextFile::InsertLine add new lines while + wxTextFile::RemoveLine deletes the existing ones. + wxTextFile::Clear resets the file to empty. + Save your changes: notice that the changes you make to the file will @b not be + saved automatically; calling wxTextFile::Close or doing + nothing discards them! To save the changes you must explicitly call + wxTextFile::Write - here, you may also change the line + termination type if you wish. + + + @library{wxbase} + @category{file} + + @seealso + wxFile +*/ +class wxTextFile +{ +public: + /** + Constructor does not load the file into memory, use Open() to do it. + */ + wxTextFile(const wxString& strFile); + + /** + Destructor does nothing. + */ + ~wxTextFile(); + + /** + Adds a line to the end of file. + */ + void AddLine(const wxString& str, + wxTextFileType type = typeDefault); + + /** + Delete all lines from the file, set current line number to 0. + */ + void Clear(); + + /** + Closes the file and frees memory, @b losing all changes. Use Write() + if you want to save them. + */ + bool Close(); + + //@{ + /** + Creates the file with the given name or the name which was given in the + @ref ctor() constructor. The array of file lines is initially + empty. + + It will fail if the file already exists, Open() should + be used in this case. + */ + bool Create(); + bool Create(const wxString& strFile); + //@} + + /** + Returns @true if the current line is the last one. + */ +#define bool Eof() /* implementation is private */ + + /** + Return @true if file exists - the name of the file should have been specified + in the constructor before calling Exists(). + */ + bool Exists(); + + /** + Returns the current line: it has meaning only when you're using + GetFirstLine()/GetNextLine() functions, it doesn't get updated when + you're using "direct access" functions like GetLine(). GetFirstLine() and + GetLastLine() also change the value of the current line, as well as + GoToLine(). + */ + size_t GetCurrentLine(); + + /** + Get the line termination string corresponding to given constant. @e typeDefault + is + the value defined during the compilation and corresponds to the native format + of the platform, i.e. it will be wxTextFileType_Dos under Windows, + wxTextFileType_Unix under Unix (including Mac OS X when compiling with the + Apple Developer Tools) and wxTextFileType_Mac under Mac OS (including + Mac OS X when compiling with CodeWarrior). + */ +#define static const char* GetEOL(wxTextFileType type = typeDefault) /* implementation is private */ + + /** + This method together with GetNextLine() + allows more "iterator-like" traversal of the list of lines, i.e. you may + write something like: + */ + wxString GetFirstLine(); + + /** + Gets the last line of the file. Together with + GetPrevLine() it allows to enumerate the lines + in the file from the end to the beginning like this: + */ + wxString GetLastLine(); + + /** + Retrieves the line number @e n from the file. The returned line may be + modified but you shouldn't add line terminator at the end - this will be done + by wxTextFile. + */ + wxString GetLine(size_t n); + + /** + Get the number of lines in the file. + */ + size_t GetLineCount(); + + /** + Get the type of the line (see also wxTextFile::GetEOL) + */ + wxTextFileType GetLineType(size_t n); + + /** + Get the name of the file. + */ + const char* GetName(); + + /** + Gets the next line (see GetFirstLine() for + the example). + */ + wxString GetNextLine(); + + /** + Gets the previous line in the file. + */ + wxString GetPrevLine(); + + /** + Changes the value returned by GetCurrentLine() + and used by wxTextFile::GetFirstLine/GetNextLine(). + */ + void GoToLine(size_t n); + + /** + Guess the type of file (which is supposed to be opened). If sufficiently + many lines of the file are in DOS/Unix/Mac format, the corresponding value will + be returned. If the detection mechanism fails wxTextFileType_None is returned. + */ + wxTextFileType GuessType(); + + /** + Insert a line before the line number @e n. + */ + void InsertLine(const wxString& str, size_t n, + wxTextFileType type = typeDefault); + + /** + Returns @true if the file is currently opened. + */ + bool IsOpened(); + + //@{ + /** + ) + + Open() opens the file with the given name or the name which was given in the + @ref ctor() constructor and also loads file in memory on + success. It will fail if the file does not exist, + Create() should be used in this case. + + The @e conv argument is only meaningful in Unicode build of wxWidgets when + it is used to convert the file to wide character representation. + */ + bool Open(); + bool Open(const wxString& strFile); + //@} + + /** + Delete line number @e n from the file. + */ + void RemoveLine(size_t n); + + /** + ) + + Change the file on disk. The @e typeNew parameter allows you to change the + file format (default argument means "don't change type") and may be used to + convert, for example, DOS files to Unix. + + The @e conv argument is only meaningful in Unicode build of wxWidgets when + it is used to convert all lines to multibyte representation before writing them + them to physical file. + + Returns @true if operation succeeded, @false if it failed. + */ + bool Write(wxTextFileType typeNew = wxTextFileType_None); + + /** + The same as GetLine(). + */ + wxString operator[](size_t n); +}; diff --git a/interface/tglbtn.h b/interface/tglbtn.h new file mode 100644 index 0000000000..998fafdfcd --- /dev/null +++ b/interface/tglbtn.h @@ -0,0 +1,176 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tglbtn.h +// Purpose: documentation for wxBitmapToggleButton class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBitmapToggleButton + @wxheader{tglbtn.h} + + wxBitmapToggleButton is a wxToggleButton + that contains a bitmap instead of text. + + This control emits an update UI event. + + @beginEventTable + @event{EVT_TOGGLEBUTTON(id\, func)}: + Handles a toggle button click event. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{bitmaptogglebutton.png} +*/ +class wxBitmapToggleButton : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a toggle button with the bitmap @e label. + Internally calls Create(). + */ + wxBitmapToggleButton(); + wxBitmapToggleButton(wxWindow* parent, wxWindowID id, + const wxBitmap& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val, + const wxString& name = "checkBox"); + //@} + + /** + Create method for two-step construction. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxBitmap& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val, + const wxString& name = "checkBox"); + + /** + Gets the state of the toggle button. + + @returns Returns @true if it is pressed, @false otherwise. + */ + bool GetValue(); + + /** + Sets the toggle button to the given state. This does not cause a + @c EVT_TOGGLEBUTTON event to be emitted. + + @param state + If @true, the button is pressed. + */ + void SetValue(bool state); +}; + + +/** + @class wxToggleButton + @wxheader{tglbtn.h} + + wxToggleButton is a button that stays pressed when clicked by the user. In + other words, it is similar to wxCheckBox in + functionality but looks like a wxButton. + + Since wxWidgets version 2.9.0 this control emits an update UI event. + + You can see wxToggleButton in action in the sixth page of the + controls sample. + + @beginEventTable + @event{EVT_TOGGLEBUTTON(id\, func)}: + Handles a toggle button click event. + @endEventTable + + @library{wxcore} + @category{ctrl} + @appearance{togglebutton.png} + + @seealso + wxCheckBox, wxButton, wxBitmapToggleButton +*/ +class wxToggleButton : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a toggle button. + + @param parent + Parent window. Must not be @NULL. + + @param id + Toggle button identifier. The value wxID_ANY indicates a default value. + + @param label + Text to be displayed next to the toggle button. + + @param pos + Toggle button position. If wxDefaultPosition is specified then a default + position is chosen. + + @param size + Toggle button size. If wxDefaultSize is specified then a default + size is chosen. + + @param style + Window style. See wxToggleButton. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxToggleButton(); + wxToggleButton(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val, + const wxString& name = "checkBox"); + //@} + + /** + Destructor, destroying the toggle button. + */ + ~wxToggleButton(); + + /** + Creates the toggle button for two-step construction. See wxToggleButton() + for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val, + const wxString& name = "checkBox"); + + /** + Gets the state of the toggle button. + + @returns Returns @true if it is pressed, @false otherwise. + */ + bool GetValue(); + + /** + Sets the toggle button to the given state. This does not cause a + @c EVT_TOGGLEBUTTON event to be emitted. + + @param state + If @true, the button is pressed. + */ + void SetValue(bool state); +}; diff --git a/interface/thread.h b/interface/thread.h new file mode 100644 index 0000000000..7906d2e859 --- /dev/null +++ b/interface/thread.h @@ -0,0 +1,1076 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: thread.h +// Purpose: documentation for wxCondition class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCondition + @wxheader{thread.h} + + wxCondition variables correspond to pthread conditions or to Win32 event + objects. They may be used in a multithreaded application to wait until the + given condition becomes @true which happens when the condition becomes signaled. + + For example, if a worker thread is doing some long task and another thread has + to wait until it is finished, the latter thread will wait on the condition + object and the worker thread will signal it on exit (this example is not + perfect because in this particular case it would be much better to just + wxThread::Wait for the worker thread, but if there are several + worker threads it already makes much more sense). + + Note that a call to wxCondition::Signal may happen before the + other thread calls wxCondition::Wait and, just as with the + pthread conditions, the signal is then lost and so if you want to be sure that + you don't miss it you must keep the mutex associated with the condition + initially locked and lock it again before calling + wxCondition::Signal. Of course, this means that this call is + going to block until wxCondition::Wait is called by another + thread. + + @library{wxbase} + @category{thread} + + @seealso + wxThread, wxMutex +*/ +class wxCondition +{ +public: + /** + Default and only constructor. The @e mutex must be locked by the caller + before calling Wait() function. + + Use IsOk() to check if the object was successfully + initialized. + */ + wxCondition(wxMutex& mutex); + + /** + Destroys the wxCondition object. The destructor is not virtual so this class + should not be used polymorphically. + */ + ~wxCondition(); + + /** + Broadcasts to all waiting threads, waking all of them up. Note that this method + may be called whether the mutex associated with this condition is locked or + not. + + @sa Signal() + */ + void Broadcast(); + + /** + Returns @true if the object had been initialized successfully, @false + if an error occurred. + */ +#define bool IsOk() /* implementation is private */ + + /** + 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. + + @sa Broadcast() + */ + void Signal(); + + /** + Waits until the condition is signalled. + + This method atomically releases the lock on the mutex associated with this + condition (this is why it must be locked prior to calling Wait) and puts the + thread to sleep until Signal() or + Broadcast() is called. It then locks the mutex + again and returns. + + Note that even if Signal() had been called before + Wait without waking up any thread, the thread would still wait for another one + and so it is important to ensure that the condition will be signalled after + Wait or the thread may sleep forever. + + @returns Returns wxCOND_NO_ERROR on success, another value if an error + occurred. + + @sa WaitTimeout() + */ + wxCondError Wait(); + + /** + Waits until the condition is signalled or the timeout has elapsed. + + This method is identical to Wait() except that it + returns, with the return code of @c wxCOND_TIMEOUT as soon as the given + timeout expires. + + @param milliseconds + Timeout in milliseconds + */ + wxCondError WaitTimeout(unsigned long milliseconds); +}; + + +/** + @class wxCriticalSectionLocker + @wxheader{thread.h} + + This is a small helper class to be used with wxCriticalSection + objects. A wxCriticalSectionLocker enters the critical section in the + constructor and leaves it in the destructor making it much more difficult to + forget to leave a critical section (which, in general, will lead to serious + and difficult to debug problems). + + Example of using it: + + @code + void Set Foo() + { + // gs_critSect is some (global) critical section guarding access to the + // object "foo" + wxCriticalSectionLocker locker(gs_critSect); + + if ( ... ) + { + // do something + ... + + return; + } + + // do something else + ... + + return; + } + @endcode + + Without wxCriticalSectionLocker, you would need to remember to manually leave + the critical section before each @c return. + + @library{wxbase} + @category{thread} + + @seealso + wxCriticalSection, wxMutexLocker +*/ +class wxCriticalSectionLocker +{ +public: + /** + Constructs a wxCriticalSectionLocker object associated with given + @e criticalsection and enters it. + */ + wxCriticalSectionLocker(wxCriticalSection& criticalsection); + + /** + Destructor leaves the critical section. + */ + ~wxCriticalSectionLocker(); +}; + + +/** + @class wxThreadHelper + @wxheader{thread.h} + + The wxThreadHelper class is a mix-in class that manages a single background + thread. By deriving from wxThreadHelper, a class can implement the thread + code in its own wxThreadHelper::Entry method + and easily share data and synchronization objects between the main thread + and the worker thread. Doing this prevents the awkward passing of pointers + that is needed when the original object in the main thread needs to + synchronize with its worker thread in its own wxThread derived object. + + For example, wxFrame may need to make some calculations + in a background thread and then display the results of those calculations in + the main window. + + Ordinarily, a wxThread derived object would be created + with the calculation code implemented in + wxThread::Entry. To access the inputs to the + calculation, the frame object would often to pass a pointer to itself to the + thread object. Similarly, the frame object would hold a pointer to the + thread object. Shared data and synchronization objects could be stored in + either object though the object without the data would have to access the + data through a pointer. + + However, with wxThreadHelper, the frame object and the thread object are + treated as the same object. Shared data and synchronization variables are + stored in the single object, eliminating a layer of indirection and the + associated pointers. + + @library{wxbase} + @category{thread} + + @seealso + wxThread +*/ +class wxThreadHelper +{ +public: + /** + This constructor simply initializes a member variable. + */ + wxThreadHelper(); + + /** + The destructor frees the resources associated with the thread. + */ + ~wxThreadHelper(); + + /** + Creates a new thread. The thread object is created in the suspended state, and + you + should call @ref wxThread::run GetThread()-Run to start running + it. You may optionally specify the stack size to be allocated to it (Ignored on + platforms that don't support setting it explicitly, eg. Unix). + + @returns One of: + */ + wxThreadError Create(unsigned int stackSize = 0); + + /** + This is the entry point of the thread. This function is pure virtual and must + be implemented by any derived class. The thread execution will start here. + + The returned value is the thread exit code which is only useful for + joinable threads and is the value returned by + @ref wxThread::wait GetThread()-Wait. + + This function is called by wxWidgets itself and should never be called + directly. + */ + virtual ExitCode Entry(); + + /** + This is a public function that returns the wxThread object + associated with the thread. + */ + wxThread * GetThread(); + + /** + wxThread * m_thread + + the actual wxThread object. + */ +}; + + +/** + @class wxCriticalSection + @wxheader{thread.h} + + A critical section object is used for exactly the same purpose as + mutexes. The only difference is that under Windows platform + critical sections are only visible inside one process, while mutexes may be + shared 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. + + @library{wxbase} + @category{thread} + + @seealso + wxThread, wxCondition, wxCriticalSectionLocker +*/ +class wxCriticalSection +{ +public: + /** + Default constructor initializes critical section object. + */ + wxCriticalSection(); + + /** + Destructor frees the resources. + */ + ~wxCriticalSection(); + + /** + Enter the critical section (same as locking a mutex). There is no error return + for this function. After entering the critical section protecting some global + data the thread running in critical section may safely use/modify it. + */ + void Enter(); + + /** + Leave the critical section allowing other threads use the global data protected + by it. There is no error return for this function. + */ + void Leave(); +}; + + +/** + @class wxThread + @wxheader{thread.h} + + A thread is basically a path of execution through a program. Threads are + sometimes called @e light-weight processes, but the fundamental difference + between threads and processes is that memory spaces of different processes are + separated while all threads share the same address space. + + While it makes it much easier to share common data between several threads, it + also + makes it much easier to shoot oneself in the foot, so careful use of + synchronization + objects such as mutexes or @ref overview_wxcriticalsection "critical sections" + is recommended. In addition, don't create global thread + objects because they allocate memory in their constructor, which will cause + problems for the memory checking system. + + @library{wxbase} + @category{thread} + + @seealso + wxMutex, wxCondition, wxCriticalSection +*/ +class wxThread +{ +public: + /** + This constructor creates a new detached (default) or joinable C++ thread + object. It + does not create or start execution of the real thread -- for this you should + use the Create() and Run() methods. + + The possible values for @e kind parameters are: + + + @b wxTHREAD_DETACHED + + + Creates a detached thread. + + @b wxTHREAD_JOINABLE + + + Creates a joinable thread. + */ + wxThread(wxThreadKind kind = wxTHREAD_DETACHED); + + /** + The destructor frees the resources associated with the thread. Notice that you + should never delete a detached thread -- you may only call + Delete() on it or wait until it terminates (and auto + destructs) itself. Because the detached threads delete themselves, they can + only be allocated on the heap. + + Joinable threads should be deleted explicitly. The Delete() and Kill() functions + will not delete the C++ thread object. It is also safe to allocate them on + stack. + */ + ~wxThread(); + + /** + Creates a new thread. The thread object is created in the suspended state, and + you + should call Run() to start running it. You may optionally + specify the stack size to be allocated to it (Ignored on platforms that don't + support setting it explicitly, eg. Unix system without + @c pthread_attr_setstacksize). If you do not specify the stack size, + the system's default value is used. + + @b Warning: It is a good idea to explicitly specify a value as systems' + default values vary from just a couple of KB on some systems (BSD and + OS/2 systems) to one or several MB (Windows, Solaris, Linux). So, if you + have a thread that requires more than just a few KB of memory, you will + have mysterious problems on some platforms but not on the common ones. On the + other hand, just indicating a large stack size by default will give you + performance issues on those systems with small default stack since those + typically use fully committed memory for the stack. On the contrary, if + use a lot of threads (say several hundred), virtual adress space can get tight + unless you explicitly specify a smaller amount of thread stack space for each + thread. + + @returns One of: + */ + wxThreadError Create(unsigned int stackSize = 0); + + /** + Calling Delete() gracefully terminates a + detached thread, either when the thread calls TestDestroy() or finished + processing. + + (Note that while this could work on a joinable thread you simply should not + call this routine on one as afterwards you may not be able to call + Wait() to free the memory of that thread). + + See @ref overview_deletionwxthread "wxThread deletion" for a broader + explanation of this routine. + */ + wxThreadError Delete(); + + /** + A common problem users experience with wxThread is that in their main thread + they will check the thread every now and then to see if it has ended through + IsRunning(), only to find that their + application has run into problems because the thread is using the default + behavior and has already deleted itself. Naturally, they instead attempt to + use joinable threads in place of the previous behavior. + + However, polling a wxThread for when it has ended is in general a bad idea - + in fact calling a routine on any running wxThread should be avoided if + possible. Instead, find a way to notify yourself when the thread has ended. + Usually you only need to notify the main thread, in which case you can post + an event to it via wxPostEvent or + wxEvtHandler::AddPendingEvent. In + the case of secondary threads you can call a routine of another class + when the thread is about to complete processing and/or set the value + of a variable, possibly using mutexes and/or other + synchronization means if necessary. + */ + + + /** + This is the entry point of the thread. This function is pure virtual and must + be implemented by any derived class. The thread execution will start here. + + The returned value is the thread exit code which is only useful for + joinable threads and is the value returned by Wait(). + + This function is called by wxWidgets itself and should never be called + directly. + */ + virtual ExitCode Entry(); + + /** + This is a protected function of the wxThread class and thus can only be called + from a derived class. It also can only be called in the context of this + thread, i.e. a thread can only exit from itself, not from another thread. + + This function will terminate the OS thread (i.e. stop the associated path of + execution) and also delete the associated C++ object for detached threads. + OnExit() will be called just before exiting. + */ + void Exit(ExitCode exitcode = 0); + + /** + Returns the number of system CPUs or -1 if the value is unknown. + + @sa SetConcurrency() + */ + static int GetCPUCount(); + + /** + Returns the platform specific thread ID of the current thread as a + long. This can be used to uniquely identify threads, even if they are + not wxThreads. + */ + static unsigned long GetCurrentId(); + + /** + Gets the thread identifier: this is a platform dependent number that uniquely + identifies the + thread throughout the system during its existence (i.e. the thread identifiers + may be reused). + */ + unsigned long GetId(); + + /** + Gets the priority of the thread, between zero and 100. + + The following priorities are defined: + + + @b WXTHREAD_MIN_PRIORITY + + + 0 + + @b WXTHREAD_DEFAULT_PRIORITY + + + 50 + + @b WXTHREAD_MAX_PRIORITY + + + 100 + */ + int GetPriority(); + + /** + Returns @true if the thread is alive (i.e. started and not terminating). + + Note that this function can only safely be used with joinable threads, not + detached ones as the latter delete themselves and so when the real thread is + no longer alive, it is not possible to call this function because + the wxThread object no longer exists. + */ + bool IsAlive(); + + /** + Returns @true if the thread is of the detached kind, @false if it is a + joinable + one. + */ + bool IsDetached(); + + /** + Returns @true if the calling thread is the main application thread. + */ + static bool IsMain(); + + /** + Returns @true if the thread is paused. + */ + bool IsPaused(); + + /** + Returns @true if the thread is running. + + This method may only be safely used for joinable threads, see the remark in + IsAlive(). + */ + bool IsRunning(); + + /** + Immediately terminates the target thread. @b This function is dangerous and + should + be used with extreme care (and not used at all whenever possible)! The resources + allocated to the thread will not be freed and the state of the C runtime library + may become inconsistent. Use Delete() for detached + threads or Wait() for joinable threads instead. + + For detached threads Kill() will also delete the associated C++ object. + However this will not happen for joinable threads and this means that you will + still have to delete the wxThread object yourself to avoid memory leaks. + In neither case OnExit() of the dying thread will be + called, so no thread-specific cleanup will be performed. + + This function can only be called from another thread context, i.e. a thread + cannot kill itself. + + It is also an error to call this function for a thread which is not running or + paused (in the latter case, the thread will be resumed first) -- if you do it, + a @c wxTHREAD_NOT_RUNNING error will be returned. + */ + wxThreadError Kill(); + + /** + Called when the thread exits. This function is called in the context of the + thread associated with the wxThread object, not in the context of the main + thread. This function will not be called if the thread was + @ref kill() killed. + + This function should never be called directly. + */ + void OnExit(); + + /** + Suspends the thread. Under some implementations (Win32), the thread is + suspended immediately, under others it will only be suspended when it calls + TestDestroy() for the next time (hence, if the + thread doesn't call it at all, it won't be suspended). + + This function can only be called from another thread context. + */ + wxThreadError Pause(); + + /** + Resumes a thread suspended by the call to Pause(). + + This function can only be called from another thread context. + */ + wxThreadError Resume(); + + /** + Starts the thread execution. Should be called after + Create(). + + This function can only be called from another thread context. + */ +#define wxThreadError Run() /* implementation is private */ + + /** + Sets the thread concurrency level for this process. This is, roughly, the + number of threads that the system tries to schedule to run in parallel. + The value of 0 for @e level may be used to set the default one. + + Returns @true on success or @false otherwise (for example, if this function is + not implemented for this platform -- currently everything except Solaris). + */ + static bool SetConcurrency(size_t level); + + /** + Sets the priority of the thread, between 0 and 100. It can only be set + after calling Create() but before calling + Run(). + + The following priorities are already defined: + + + @b WXTHREAD_MIN_PRIORITY + + + 0 + + @b WXTHREAD_DEFAULT_PRIORITY + + + 50 + + @b WXTHREAD_MAX_PRIORITY + + + 100 + */ + void SetPriority(int priority); + + /** + Pauses the thread execution for the given amount of time. + + This function should be used instead of wxSleep by all worker + threads (i.e. all except the main one). + */ + static void Sleep(unsigned long milliseconds); + + /** + This function should be called periodically by the thread to ensure that calls + to Pause() and Delete() will + work. If it returns @true, the thread should exit as soon as possible. + + Notice that under some platforms (POSIX), implementation of + Pause() also relies on this function being called, so + not calling it would prevent both stopping and suspending thread from working. + */ + virtual bool TestDestroy(); + + /** + Return the thread object for the calling thread. @NULL is returned if the + calling thread + is the main (GUI) thread, but IsMain() should be used to test + whether the thread is really the main one because @NULL may also be returned for + the thread + not created with wxThread class. Generally speaking, the return value for such + a thread + is undefined. + */ + static wxThread * This(); + + /** + There are two types of threads in wxWidgets: @e detached and @e joinable, + modeled after the the POSIX thread API. This is different from the Win32 API + where all threads are joinable. + + By default wxThreads in wxWidgets use the detached behavior. Detached threads + delete themselves once they have completed, either by themselves when they + complete + processing or through a call to Delete(), and thus + must be created on the heap (through the new operator, for example). + Conversely, + joinable threads do not delete themselves when they are done processing and as + such + are safe to create on the stack. Joinable threads also provide the ability + for one to get value it returned from Entry() + through Wait(). + + You shouldn't hurry to create all the threads joinable, however, because this + has a disadvantage as well: you @b must Wait() for a joinable thread or the + system resources used by it will never be freed, and you also must delete the + corresponding wxThread object yourself if you did not create it on the stack. + In + contrast, detached threads are of the "fire-and-forget" kind: you only have to + start + a detached thread and it will terminate and destroy itself. + */ + + + /** + Waits for a joinable thread to terminate and returns the value the thread + returned from Entry() or @c (ExitCode)-1 on + error. Notice that, unlike Delete() doesn't cancel the + thread in any way so the caller waits for as long as it takes to the thread to + exit. + + You can only Wait() for joinable (not detached) threads. + + This function can only be called from another thread context. + + See @ref overview_deletionwxthread "wxThread deletion" for a broader + explanation of this routine. + */ + ExitCode Wait(); + + /** + Give the rest of the thread time slice to the system allowing the other threads + to run. + Note that using this function is @b strongly discouraged, since in + many cases it indicates a design weakness of your threading model (as + does using Sleep functions). + Threads should use the CPU in an efficient manner, i.e. they should + do their current work efficiently, then as soon as the work is done block + on a wakeup event (wxCondition, wxMutex, select(), poll(), ...) + which will get signalled e.g. by other threads or a user device once further + thread work is available. Using Yield or Sleep + indicates polling-type behaviour, since we're fuzzily giving up our timeslice + and wait until sometime later we'll get reactivated, at which time we + realize that there isn't really much to do and Yield again... + The most critical characteristic of Yield is that it's operating system + specific: there may be scheduler changes which cause your thread to not + wake up relatively soon again, but instead many seconds later, + causing huge performance issues for your application. @b with a + well-behaving, CPU-efficient thread the operating system is likely to properly + care for its reactivation the moment it needs it, whereas with + non-deterministic, Yield-using threads all bets are off and the system + scheduler is free to penalize drastically, and this effect gets worse + with increasing system load due to less free CPU resources available. + You may refer to various Linux kernel sched_yield discussions for more + information. + See also Sleep(). + */ + void Yield(); + + /** + Regardless of whether it has terminated or not, you should call + Wait() on a joinable thread to release its + memory, as outlined in @ref overview_typeswxthread "Types of wxThreads". If you + created + a joinable thread on the heap, remember to delete it manually with the delete + operator or similar means as only detached threads handle this type of memory + management. + + Since detached threads delete themselves when they are finished processing, + you should take care when calling a routine on one. If you are certain the + thread is still running and would like to end it, you may call + Delete() to gracefully end it (which implies + that the thread will be deleted after that call to Delete()). It should be + implied that you should never attempt to delete a detached thread with the + delete operator or similar means. + + As mentioned, Wait() or + Delete() attempts to gracefully terminate + a joinable and detached thread, respectively. It does this by waiting until + the thread in question calls TestDestroy() + or ends processing (returns from wxThread::Entry). + + Obviously, if the thread does call TestDestroy() and does not end the calling + thread will come to halt. This is why it is important to call TestDestroy() in + the Entry() routine of your threads as often as possible. + + As a last resort you can end the thread immediately through + Kill(). It is strongly recommended that you + do not do this, however, as it does not free the resources associated with + the object (although the wxThread object of detached threads will still be + deleted) and could leave the C runtime library in an undefined state. + */ + + + /** + All threads other then the "main application thread" (the one + wxApp::OnInit or your main function runs in, for + example) are considered "secondary threads". These include all threads created + by Create() or the corresponding constructors. + + GUI calls, such as those to a wxWindow or + wxBitmap are explicitly not safe at all in secondary threads + and could end your application prematurely. This is due to several reasons, + including the underlying native API and the fact that wxThread does not run a + GUI event loop similar to other APIs as MFC. + + A workaround that works on some wxWidgets ports is calling wxMutexGUIEnter + before any GUI calls and then calling wxMutexGUILeave afterwords. However, + the recommended way is to simply process the GUI calls in the main thread + through an event that is posted by either wxPostEvent or + wxEvtHandler::AddPendingEvent. This does + not imply that calls to these classes are thread-safe, however, as most + wxWidgets classes are not thread-safe, including wxString. + */ +}; + + +/** + @class wxSemaphore + @wxheader{thread.h} + + wxSemaphore is a counter limiting the number of threads concurrently accessing + a shared resource. This counter is always between 0 and the maximum value + specified during the semaphore creation. When the counter is strictly greater + than 0, a call to wxSemaphore::Wait returns immediately and + decrements the counter. As soon as it reaches 0, any subsequent calls to + wxSemaphore::Wait block and only return when the semaphore + counter becomes strictly positive again as the result of calling + wxSemaphore::Post which increments the counter. + + In general, semaphores are useful to restrict access to a shared resource + which can only be accessed by some fixed number of clients at the same time. For + example, when modeling a hotel reservation system a semaphore with the counter + equal to the total number of available rooms could be created. Each time a room + is reserved, the semaphore should be acquired by calling + wxSemaphore::Wait and each time a room is freed it should be + released by calling wxSemaphore::Post. + + @library{wxbase} + @category{thread} +*/ +class wxSemaphore +{ +public: + /** + Specifying a @e maxcount of 0 actually makes wxSemaphore behave as if + there is no upper limit. If maxcount is 1, the semaphore behaves almost as a + mutex (but unlike a mutex it can be released by a thread different from the one + which acquired it). + + @e initialcount is the initial value of the semaphore which must be between + 0 and @e maxcount (if it is not set to 0). + */ + wxSemaphore(int initialcount = 0, int maxcount = 0); + + /** + Destructor is not virtual, don't use this class polymorphically. + */ + ~wxSemaphore(); + + /** + Increments the semaphore count and signals one of the waiting + threads in an atomic way. Returns wxSEMA_OVERFLOW if the count + would increase the counter past the maximum. + + @returns One of: + */ + wxSemaError Post(); + + /** + Same as Wait(), but returns immediately. + + @returns One of: + */ + wxSemaError TryWait(); + + /** + Wait indefinitely until the semaphore count becomes strictly positive + and then decrement it and return. + + @returns One of: + */ + wxSemaError Wait(); +}; + + +/** + @class wxMutexLocker + @wxheader{thread.h} + + This is a small helper class to be used with wxMutex + objects. A wxMutexLocker acquires a mutex lock in the constructor and releases + (or unlocks) the mutex in the destructor making it much more difficult to + forget to release a mutex (which, in general, will promptly lead to serious + problems). See wxMutex for an example of wxMutexLocker + usage. + + @library{wxbase} + @category{thread} + + @seealso + wxMutex, wxCriticalSectionLocker +*/ +class wxMutexLocker +{ +public: + /** + Constructs a wxMutexLocker object associated with mutex and locks it. + Call @ref isok() IsLocked to check if the mutex was + successfully locked. + */ + wxMutexLocker(wxMutex& mutex); + + /** + Destructor releases the mutex if it was successfully acquired in the ctor. + */ + ~wxMutexLocker(); + + /** + Returns @true if mutex was acquired in the constructor, @false otherwise. + */ +#define bool IsOk() /* implementation is private */ +}; + + +/** + @class wxMutex + @wxheader{thread.h} + + A mutex object is a synchronization object whose state is set to signaled when + it is not owned by any thread, and nonsignaled when it is owned. Its name comes + from its usefulness in coordinating mutually-exclusive access to a shared + resource as only one thread at a time can own a mutex object. + + Mutexes may be recursive in the sense that a thread can lock a mutex which it + had already locked before (instead of dead locking the entire process in this + situation by starting to wait on a mutex which will never be released while the + thread is waiting) but using them is not recommended under Unix and they are + @b not recursive there by default. The reason for this is that recursive + mutexes are not supported by all Unix flavours and, worse, they cannot be used + with wxCondition. On the other hand, Win32 mutexes are + always recursive. + + For example, when several threads use the data stored in the linked list, + modifications to the list should only be allowed to one thread at a time + because during a new node addition the list integrity is temporarily broken + (this is also called @e program invariant). + + @library{wxbase} + @category{thread} + + @seealso + wxThread, wxCondition, wxMutexLocker, wxCriticalSection +*/ +class wxMutex +{ +public: + /** + Default constructor. + */ + wxMutex(wxMutexType type = wxMUTEX_DEFAULT); + + /** + Destroys the wxMutex object. + */ + ~wxMutex(); + + /** + Locks the mutex object. This is equivalent to + LockTimeout() with infinite timeout. + + @returns One of: + */ + wxMutexError Lock(); + + /** + Try to lock the mutex object during the specified time interval. + + @returns One of: + */ + wxMutexError LockTimeout(unsigned long msec); + + /** + Tries to lock the mutex object. If it can't, returns immediately with an error. + + @returns One of: + */ + wxMutexError TryLock(); + + /** + Unlocks the mutex object. + + @returns One of: + */ + wxMutexError Unlock(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Returns @true if this thread is the main one. Always returns @true if + @c wxUSE_THREADS is 0. +*/ +bool wxIsMainThread(); + +/** + This macro combines wxCRIT_SECT_DECLARE and + wxCRIT_SECT_LOCKER: it creates a static critical + section object and also the lock object associated with it. Because of this, it + can be only used inside a function, not at global scope. For example: + @code + int IncCount() + { + static int s_counter = 0; + + wxCRITICAL_SECTION(counter); + + return ++s_counter; + } + @endcode + + (note that we suppose that the function is called the first time from the main + thread so that the critical section object is initialized correctly by the time + other threads start calling it, if this is not the case this approach can + @b not be used and the critical section must be made a global instead). +*/ +#define wxCRITICAL_SECTION(name) /* implementation is private */ + +/** + This macro declares a critical section object named @e cs if + @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't + include the @c static keyword (unlike + wxCRIT_SECT_DECLARE), it can be used to declare + a class or struct member which explains its name. +*/ +#define wxCRIT_SECT_DECLARE(cs) /* implementation is private */ + +/** + This function must be called when any thread other than the main GUI thread + wants to get access to the GUI library. This function will block the execution + of the calling thread until the main thread (or any other thread holding the + main GUI lock) leaves the GUI library and no other thread will enter the GUI + library until the calling thread calls ::wxMutexGuiLeave. + + Typically, these functions are used like this: + @code + void MyThread::Foo(void) + { + // before doing any GUI calls we must ensure that this thread is the only + // one doing it! + + wxMutexGuiEnter(); + + // Call GUI here: + my_window-DrawSomething(); + + wxMutexGuiLeave(); + } + @endcode + + Note that under GTK, no creation of top-level windows is allowed in any + thread but the main one. + + This function is only defined on platforms which support preemptive + threads. +*/ +void wxMutexGuiEnter(); + +/** + This macro declares a (static) critical section object named @e cs if + @c wxUSE_THREADS is 1 and does nothing if it is 0. +*/ +#define wxCRIT_SECT_DECLARE(cs) /* implementation is private */ + +/** + This macro is equivalent to @ref wxCriticalSection::leave cs.Leave if + @c wxUSE_THREADS is 1 and does nothing if it is 0. +*/ +#define wxLEAVE_CRIT_SECT(wxCriticalSection& cs) /* implementation is private */ + +/** + This macro creates a @ref overview_wxcriticalsectionlocker "critical section + lock" + object named @e name and associated with the critical section @e cs if + @c wxUSE_THREADS is 1 and does nothing if it is 0. +*/ +#define wxCRIT_SECT_LOCKER(name, cs) /* implementation is private */ + +/** + This macro is equivalent to @ref wxCriticalSection::enter cs.Enter if + @c wxUSE_THREADS is 1 and does nothing if it is 0. +*/ +#define wxENTER_CRIT_SECT(wxCriticalSection& cs) /* implementation is private */ + diff --git a/interface/timer.h b/interface/timer.h new file mode 100644 index 0000000000..9099f0db44 --- /dev/null +++ b/interface/timer.h @@ -0,0 +1,189 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: timer.h +// Purpose: documentation for wxTimer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTimer + @wxheader{timer.h} + + The wxTimer class allows you to execute code at specified intervals. Its + precision is platform-dependent, but in general will not be better than 1ms nor + worse than 1s. + + There are three different ways to use this class: + + You may derive a new class from wxTimer and override the + wxTimer::Notify member to perform the required action. + Or you may redirect the notifications to any + wxEvtHandler derived object by using the non-default + constructor or wxTimer::SetOwner. Then use the @c EVT_TIMER + macro to connect it to the event handler which will receive + wxTimerEvent notifications. + Or you may use a derived class and the @c EVT_TIMER + macro to connect it to an event handler defined in the derived class. + If the default constructor is used, the timer object will be its + own owner object, since it is derived from wxEvtHandler. + + In any case, you must start the timer with wxTimer::Start + after constructing it before it actually starts sending notifications. It can + be stopped later with wxTimer::Stop. + + @b Note: A timer can only be used from the main thread. + + @library{wxbase} + @category{misc} + + @seealso + wxStopWatch +*/ +class wxTimer : public wxEvtHandler +{ +public: + //@{ + /** + Creates a timer and associates it with @e owner. Please see + SetOwner() for the description of parameters. + */ + wxTimer(); + wxTimer(wxEvtHandler * owner, int id = -1); + //@} + + /** + Destructor. Stops the timer if it is running. + */ + ~wxTimer(); + + /** + Returns the ID of the events generated by this timer. + */ + int GetId(); + + /** + Returns the current interval for the timer (in milliseconds). + */ + int GetInterval(); + + /** + Returns the current @e owner of the timer. + If non-@NULL this is the event handler which will receive the + @ref overview_wxtimerevent "timer events" when the timer is running. + */ + wxEvtHandler GetOwner(); + + /** + Returns @true if the timer is one shot, i.e. if it will stop after firing the + first notification automatically. + */ + bool IsOneShot(); + + /** + Returns @true if the timer is running, @false if it is stopped. + */ + bool IsRunning(); + + /** + This member should be overridden by the user if the default constructor was + used and SetOwner() wasn't called. + + Perform whatever action which is to be taken periodically here. + */ + void Notify(); + + /** + Associates the timer with the given @e owner object. When the timer is + running, the owner will receive @ref overview_wxtimerevent "timer events" with + id equal to @e id specified here. + */ + void SetOwner(wxEvtHandler * owner, int id = -1); + + /** + (Re)starts the timer. If @e milliseconds parameter is -1 (value by default), + the previous value is used. Returns @false if the timer could not be started, + @true otherwise (in MS Windows timers are a limited resource). + + If @e oneShot is @false (the default), the Notify() + function will be called repeatedly until the timer is stopped. If @true, + it will be called only once and the timer will stop automatically. To make your + code more readable you may also use the following symbolic constants: + + + wxTIMER_CONTINUOUS + + + Start a normal, continuously running, timer + + wxTIMER_ONE_SHOT + + + Start a one shot timer + + If the timer was already running, it will be stopped by this method before + restarting it. + */ + bool Start(int milliseconds = -1, bool oneShot = @false); + + /** + Stops the timer. + */ + void Stop(); +}; + + +/** + @class wxTimerEvent + @wxheader{timer.h} + + wxTimerEvent object is passed to the event handler of timer events. + + For example: + + @code + class MyFrame : public wxFrame + { + public: + ... + void OnTimer(wxTimerEvent& event); + + private: + wxTimer m_timer; + }; + + BEGIN_EVENT_TABLE(MyFrame, wxFrame) + EVT_TIMER(TIMER_ID, MyFrame::OnTimer) + END_EVENT_TABLE() + + MyFrame::MyFrame() + : m_timer(this, TIMER_ID) + { + m_timer.Start(1000); // 1 second interval + } + + void MyFrame::OnTimer(wxTimerEvent& event) + { + // do whatever you want to do every second here + } + @endcode + + @library{wxbase} + @category{events} + + @seealso + wxTimer +*/ +class wxTimerEvent : public wxEvent +{ +public: + /** + Returns the interval of the timer which generated this event. + */ + int GetInterval(); + + /** + Returns the timer object which generated this event. + */ + wxTimer GetTimer(); +}; diff --git a/interface/tipdlg.h b/interface/tipdlg.h new file mode 100644 index 0000000000..4f0e01d182 --- /dev/null +++ b/interface/tipdlg.h @@ -0,0 +1,88 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tipdlg.h +// Purpose: documentation for wxTipProvider class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTipProvider + @wxheader{tipdlg.h} + + This is the class used together with wxShowTip function. + It must implement wxTipProvider::GetTip function and return the + current tip from it (different tip each time it is called). + + You will never use this class yourself, but you need it to show startup tips + with wxShowTip. Also, if you want to get the tips text from elsewhere than a + simple text file, you will want to derive a new class from wxTipProvider and + use it instead of the one returned by wxCreateFileTipProvider. + + @library{wxadv} + @category{FIXME} + + @seealso + @ref overview_tipsoverview "Startup tips overview", ::wxShowTip +*/ +class wxTipProvider +{ +public: + /** + Constructor. + + @param currentTip + The starting tip index. + */ + wxTipProvider(size_t currentTip); + + /** + Returns the index of the current tip (i.e. the one which would be returned by + GetTip). + + The program usually remembers the value returned by this function after calling + wxShowTip. Note that it is not the same as the value which + was passed to wxShowTip + 1 because the user might have pressed the "Next" + button in the tip dialog. + */ + size_t GetCurrentTip(); + + /** + Return the text of the current tip and pass to the next one. This function is + pure virtual, it should be implemented in the derived classes. + */ + wxString GetTip(); + + /** + Returns a modified tip. This function will be called immediately after read, + and before being check whether it is a comment, an empty string or a string + to translate. You can optionally override this in your custom user-derived + class + to optionally to modify the tip as soon as it is read. You can return any + modification to the string. If you return wxEmptyString, then this tip is + skipped, and the next one is read. + */ + virtual wxString PreProcessTip(const wxString& tip); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + This function creates a wxTipProvider which may be + used with wxShowTip. + + @param filename + The name of the file containing the tips, one per line + + @param currentTip + The index of the first tip to show - normally this index + is remembered between the 2 program runs. + + @sa @ref overview_tipsoverview "Tips overview" +*/ +wxTipProvider * wxCreateFileTipProvider(const wxString& filename, + size_t currentTip); + diff --git a/interface/tipwin.h b/interface/tipwin.h new file mode 100644 index 0000000000..a38de3ec0c --- /dev/null +++ b/interface/tipwin.h @@ -0,0 +1,76 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tipwin.h +// Purpose: documentation for wxTipWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTipWindow + @wxheader{tipwin.h} + + Shows simple text in a popup tip window on creation. This is used by + wxSimpleHelpProvider to show popup help. The + window automatically destroys itself when the user clicks on it or it loses the + focus. + + You may also use this class to emulate the tooltips when you need finer + control over them than what the standard tooltips provide. + + @library{wxcore} + @category{managedwnd} +*/ +class wxTipWindow : public wxWindow +{ +public: + /** + Constructor. The tip is shown immediately after the window is constructed. + + @param parent + The parent window, must be non-@NULL + + @param text + The text to show, may contain the new line characters + + @param maxLength + The length of each line, in pixels. Set to a very large + value to avoid wrapping lines + + @param windowPtr + Simply passed to + SetTipWindowPtr below, please see its + documentation for the description of this parameter + + @param rectBounds + If non-@NULL, passed to + SetBoundingRect below, please see its + documentation for the description of this parameter + */ + wxTipWindow(wxWindow* parent, const wxString& text, + wxCoord maxLength = 100, + wxTipWindow** windowPtr, + wxRect * rectBounds = @NULL); + + /** + By default, the tip window disappears when the user clicks the mouse or presses + a keyboard key or if it loses focus in any other way - for example because the + user switched to another application window. + + Additionally, if a non-empty @e rectBound is provided, the tip window will + also automatically close if the mouse leaves this area. This is useful to + dismiss the tip mouse when the mouse leaves the object it is associated with. + + @param rectBound + The bounding rectangle for the mouse in the screen coordinates + */ + void SetBoundingRect(const wxRect& rectBound); + + /** + When the tip window closes itself (which may happen at any moment and + unexpectedly to the caller) it may @NULL out the pointer pointed to by + @e it windowPtr. This is helpful to avoid dereferencing the tip window which + had been already closed and deleted. + */ + void SetTipWindowPtr(wxTipWindow** windowPtr); +}; diff --git a/interface/tokenzr.h b/interface/tokenzr.h new file mode 100644 index 0000000000..f6fe5dadff --- /dev/null +++ b/interface/tokenzr.h @@ -0,0 +1,169 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tokenzr.h +// Purpose: documentation for wxStringTokenizer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStringTokenizer + @wxheader{tokenzr.h} + + wxStringTokenizer helps you to break a string up into a number of tokens. It + replaces the standard C function @c strtok() and also extends it in a + number of ways. + + To use this class, you should create a wxStringTokenizer object, give it the + string to tokenize and also the delimiters which separate tokens in the string + (by default, white space characters will be used). + + Then wxStringTokenizer::GetNextToken may be called + repeatedly until it wxStringTokenizer::HasMoreTokens + returns @false. + + For example: + + @code + wxStringTokenizer tkz(wxT("first:second:third:fourth"), wxT(":")); + while ( tkz.HasMoreTokens() ) + { + wxString token = tkz.GetNextToken(); + + // process token here + } + @endcode + + By default, wxStringTokenizer will behave in the same way as @c strtok() if + the delimiters string only contains white space characters but, unlike the + standard function, it will return empty tokens if this is not the case. This + is helpful for parsing strictly formatted data where the number of fields is + fixed but some of them may be empty (i.e. @c TAB or comma delimited text + files). + + The behaviour is governed by the last + @ref wxStringTokenizer::wxstringtokenizer + constructor/wxStringTokenizer::SetString + parameter @c mode which may be one of the following: + + + + @c wxTOKEN_DEFAULT + + + Default behaviour (as described above): + same as @c wxTOKEN_STRTOK if the delimiter string contains only + whitespaces, same as @c wxTOKEN_RET_EMPTY otherwise + + + @c wxTOKEN_RET_EMPTY + + + In this mode, the empty tokens in the + middle of the string will be returned, i.e. @c "a::b:" will be tokenized in + three tokens 'a', '' and 'b'. Notice that all trailing delimiters are ignored + in this mode, not just the last one, i.e. a string @c "a::b::" would + still result in the same set of tokens. + + + @c wxTOKEN_RET_EMPTY_ALL + + + In this mode, empty trailing tokens + (including the one after the last delimiter character) will be returned as + well. The string @c "a::b:" will be tokenized in four tokens: the already + mentioned ones and another empty one as the last one and a string + @c "a::b::" will have five tokens. + + + @c wxTOKEN_RET_DELIMS + + + In this mode, the delimiter character + after the end of the current token (there may be none if this is the last + token) is returned appended to the token. Otherwise, it is the same mode as + @c wxTOKEN_RET_EMPTY. Notice that there is no mode like this one but + behaving like @c wxTOKEN_RET_EMPTY_ALL instead of + @c wxTOKEN_RET_EMPTY, use @c wxTOKEN_RET_EMPTY_ALL and + wxStringTokenizer::GetLastDelimiter to emulate it. + + + @c wxTOKEN_STRTOK + + + In this mode the class behaves exactly like + the standard @c strtok() function: the empty tokens are never returned. + + + + @library{wxbase} + @category{data} + + @seealso + wxStringTokenize +*/ +class wxStringTokenizer : public wxObject +{ +public: + //@{ + /** + Constructor. Pass the string to tokenize, a string containing delimiters + and the mode specifying how the string should be tokenized. + */ + wxStringTokenizer(); + wxStringTokenizer(const wxString& str, + const wxString& delims = " \t\r\n", + wxStringTokenizerMode mode = wxTOKEN_DEFAULT); + //@} + + /** + Returns the number of tokens remaining in the input string. The number of + tokens returned by this function is decremented each time + GetNextToken() is called and when it + reaches 0 HasMoreTokens() returns + @false. + */ + int CountTokens(); + + /** + Returns the delimiter which ended scan for the last token returned by + GetNextToken() or @c NUL if + there had been no calls to this function yet or if it returned the trailing + empty token in @c wxTOKEN_RET_EMPTY_ALL mode. + + This function is new since wxWidgets version 2.7.0 + */ + wxChar GetLastDelimiter(); + + /** + Returns the next token or empty string if the end of string was reached. + */ + wxString GetNextToken(); + + /** + Returns the current position (i.e. one index after the last returned + token or 0 if GetNextToken() has never been called) in the original + string. + */ + size_t GetPosition(); + + /** + Returns the part of the starting string without all token already extracted. + */ + wxString GetString(); + + /** + Returns @true if the tokenizer has further tokens, @false if none are left. + */ + bool HasMoreTokens(); + + /** + Initializes the tokenizer. + + Pass the string to tokenize, a string containing delimiters, + and the mode specifying how the string should be tokenized. + */ + void SetString(const wxString& to_tokenize, + const wxString& delims = " \t\r\n", + wxStringTokenizerMode mode = wxTOKEN_DEFAULT); +}; diff --git a/interface/toolbar.h b/interface/toolbar.h new file mode 100644 index 0000000000..92c864c42f --- /dev/null +++ b/interface/toolbar.h @@ -0,0 +1,659 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: toolbar.h +// Purpose: documentation for wxToolBar class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxToolBar + @wxheader{toolbar.h} + + The name wxToolBar is defined to be a synonym for one of the following classes: + + @b wxToolBar95 The native Windows 95 toolbar. Used on Windows 95, NT 4 and + above. + @b wxToolBarMSW A Windows implementation. Used on 16-bit Windows. + @b wxToolBarGTK The GTK toolbar. + + + @beginStyleTable + @style{wxTB_FLAT}: + Gives the toolbar a flat look (Windows and GTK only). + @style{wxTB_DOCKABLE}: + Makes the toolbar floatable and dockable (GTK only). + @style{wxTB_HORIZONTAL}: + Specifies horizontal layout (default). + @style{wxTB_VERTICAL}: + Specifies vertical layout. + @style{wxTB_TEXT}: + Shows the text in the toolbar buttons; by default only icons are + shown. + @style{wxTB_NOICONS}: + Specifies no icons in the toolbar buttons; by default they are + shown. + @style{wxTB_NODIVIDER}: + Specifies no divider (border) above the toolbar (Windows only). + @style{wxTB_NOALIGN}: + Specifies no alignment with the parent window (Windows only, not + very useful). + @style{wxTB_HORZ_LAYOUT}: + Shows the text and the icons alongside, not vertically stacked + (Windows and GTK 2 only). This style must be used with wxTB_TEXT. + @style{wxTB_HORZ_TEXT}: + Combination of wxTB_HORZ_LAYOUT and wxTB_TEXT. + @style{wxTB_NO_TOOLTIPS}: + Don't show the short help tooltips for the tools when the mouse + hovers over them. + @style{wxTB_BOTTOM}: + Align the toolbar at the bottom of parent window. + @style{wxTB_RIGHT}: + Align the toolbar at the right side of parent window. + @endStyleTable + + @library{wxbase} + @category{miscwnd} + + @seealso + @ref overview_wxtoolbaroverview "Toolbar overview", wxScrolledWindow +*/ +class wxToolBar : public wxControl +{ +public: + //@{ + /** + Constructs a toolbar. + + @param parent + Pointer to a parent window. + + @param id + Window identifier. If -1, will automatically create an identifier. + + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets + should generate a default position for the window. If using the wxWindow class + directly, supply + an actual position. + + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets + should generate a default size for the window. + + @param style + Window style. See wxToolBar for details. + + @param name + Window name. + + @remarks After a toolbar is created, you use AddTool() and + perhaps AddSeparator(), and then you must + call Realize() to construct and display the + toolbar tools. + */ + wxToolBar(); + wxToolBar(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTB_HORIZONTAL | wxBORDER_NONE, + const wxString& name = wxPanelNameStr); + //@} + + /** + Toolbar destructor. + */ + ~wxToolBar(); + + /** + Adds a new check (or toggle) tool to the toolbar. The parameters are the same + as in AddTool(). + + @sa AddTool() + */ + wxToolBarToolBase* AddCheckTool(int toolId, + const wxString& label, + const wxBitmap& bitmap1, + const wxBitmap& bitmap2, + const wxString& shortHelpString = "", + const wxString& longHelpString = "", + wxObject* clientData = @NULL); + + /** + Adds any control to the toolbar, typically e.g. a combobox. + + @param control + The control to be added. + + @param label + Text to be displayed near the control. + + @remarks wxMSW: the label is only displayed if there is enough space + available below the embedded control. + */ + bool AddControl(wxControl* control, const wxString label = ""); + + /** + Adds a new radio tool to the toolbar. Consecutive radio tools form a radio + group such that exactly one button in the group is pressed at any moment, in + other words whenever a button in the group is pressed the previously pressed + button is automatically released. You should avoid having the radio groups of + only one element as it would be impossible for the user to use such button. + + By default, the first button in the radio group is initially pressed, the + others are not. + + @sa AddTool() + */ + wxToolBarToolBase* AddRadioTool(int toolId, + const wxString& label, + const wxBitmap& bitmap1, + const wxBitmap& bitmap2, + const wxString& shortHelpString = "", + const wxString& longHelpString = "", + wxObject* clientData = @NULL); + + /** + Adds a separator for spacing groups of tools. + + @sa AddTool(), SetToolSeparation() + */ + void AddSeparator(); + + //@{ + /** + Adds a tool to the toolbar. The first (short and most commonly used) version + has fewer parameters than the full version at the price of not being able to + specify some of the more rarely used button features. The last version allows + you to add an existing tool. + + @param toolId + An integer by which + the tool may be identified in subsequent operations. + + @param kind + May be wxITEM_NORMAL for a normal button (default), + wxITEM_CHECK for a checkable tool (such tool stays pressed after it had been + toggled) or wxITEM_RADIO for a checkable tool which makes part of a radio + group of tools each of which is automatically unchecked whenever another button + in the group is checked + + @param bitmap1 + The primary tool bitmap. + + @param bitmap2 + The bitmap used when the tool is disabled. If it is equal to + wxNullBitmap, the disabled bitmap is automatically generated by greing the + normal one. + + @param shortHelpString + This string is used for the tools tooltip + + @param longHelpString + This string is shown in the statusbar (if any) of the + parent frame when the mouse pointer is inside the tool + + @param clientData + An optional pointer to client data which can be + retrieved later using GetToolClientData(). + + @param tool + The tool to be added. + + @remarks After you have added tools to a toolbar, you must call + Realize() in order to have the tools appear. + + @sa AddSeparator(), AddCheckTool(), AddRadioTool(), + InsertTool(), DeleteTool(), Realize() + */ + wxToolBarToolBase* AddTool(int toolId, const wxString& label, + const wxBitmap& bitmap1, + const wxString& shortHelpString = "", + wxItemKind kind = wxITEM_NORMAL); + wxToolBarToolBase* AddTool(int toolId, const wxString& label, + const wxBitmap& bitmap1, + const wxBitmap& bitmap2 = wxNullBitmap, + wxItemKind kind = wxITEM_NORMAL, + const wxString& shortHelpString = "", + const wxString& longHelpString = "", + wxObject* clientData = @NULL); + wxToolBarToolBase* AddTool(wxToolBarToolBase* tool); + //@} + + /** + Deletes all the tools in the toolbar. + */ + void ClearTools(); + + /** + Removes the specified tool from the toolbar and deletes it. If you don't want + to delete the tool, but just to remove it from the toolbar (to possibly add it + back later), you may use RemoveTool() instead. + + Note that it is unnecessary to call Realize() for the + change to take place, it will happen immediately. + + Returns @true if the tool was deleted, @false otherwise. + + @sa DeleteToolByPos() + */ + bool DeleteTool(int toolId); + + /** + This function behaves like DeleteTool() but it + deletes the tool at the specified position and not the one with the given id. + */ + bool DeleteToolByPos(size_t pos); + + /** + Enables or disables the tool. + + @param toolId + Tool to enable or disable. + + @param enable + If @true, enables the tool, otherwise disables it. + + @remarks Some implementations will change the visible state of the tool + to indicate that it is disabled. + + @sa GetToolEnabled(), ToggleTool() + */ + void EnableTool(int toolId, bool enable); + + /** + Returns a pointer to the tool identified by @e id or + @NULL if no corresponding tool is found. + */ + wxToolBarToolBase* FindById(int id); + + /** + Returns a pointer to the control identified by @e id or + @NULL if no corresponding control is found. + */ + wxControl* FindControl(int id); + + /** + Finds a tool for the given mouse position. + + @param x + X position. + + @param y + Y position. + + @returns A pointer to a tool if a tool is found, or @NULL otherwise. + + @remarks Currently not implemented in wxGTK (always returns @NULL there). + */ + wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y); + + /** + Returns the left/right and top/bottom margins, which are also used for + inter-toolspacing. + + @sa SetMargins() + */ + wxSize GetMargins(); + + /** + Returns the size of bitmap that the toolbar expects to have. The default bitmap + size is 16 by 15 pixels. + + @remarks Note that this is the size of the bitmap you pass to + AddTool(), and not the eventual size of the + tool button. + + @sa SetToolBitmapSize(), GetToolSize() + */ + wxSize GetToolBitmapSize(); + + /** + Get any client data associated with the tool. + + @param toolId + Id of the tool, as passed to AddTool(). + + @returns Client data, or @NULL if there is none. + */ + wxObject* GetToolClientData(int toolId); + + /** + Called to determine whether a tool is enabled (responds to user input). + + @param toolId + Id of the tool in question. + + @returns @true if the tool is enabled, @false otherwise. + + @sa EnableTool() + */ + bool GetToolEnabled(int toolId); + + /** + Returns the long help for the given tool. + + @param toolId + The tool in question. + + @sa SetToolLongHelp(), SetToolShortHelp() + */ + wxString GetToolLongHelp(int toolId); + + /** + Returns the value used for packing tools. + + @sa SetToolPacking() + */ + int GetToolPacking(); + + /** + Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool is not + found. + */ + int GetToolPos(int toolId); + + /** + Returns the default separator size. + + @sa SetToolSeparation() + */ + int GetToolSeparation(); + + /** + Returns the short help for the given tool. + + @param toolId + The tool in question. + + @sa GetToolLongHelp(), SetToolShortHelp() + */ + wxString GetToolShortHelp(int toolId); + + /** + Returns the size of a whole button, which is usually larger than a tool bitmap + because + of added 3D effects. + + @sa SetToolBitmapSize(), GetToolBitmapSize() + */ + wxSize GetToolSize(); + + /** + Gets the on/off state of a toggle tool. + + @param toolId + The tool in question. + + @returns @true if the tool is toggled on, @false otherwise. + + @sa ToggleTool() + */ + bool GetToolState(int toolId); + + /** + Returns the number of tools in the toolbar. + */ + int GetToolsCount(); + + /** + Inserts the control into the toolbar at the given position. + + You must call Realize() for the change to take place. + + @sa AddControl(), InsertTool() + */ + wxToolBarToolBase * InsertControl(size_t pos, + wxControl * control); + + /** + Inserts the separator into the toolbar at the given position. + + You must call Realize() for the change to take place. + + @sa AddSeparator(), InsertTool() + */ + wxToolBarToolBase * InsertSeparator(size_t pos); + + //@{ + /** + Inserts the tool with the specified attributes into the toolbar at the given + position. + + You must call Realize() for the change to take place. + + @sa AddTool(), InsertControl(), InsertSeparator() + */ + wxToolBarToolBase * InsertTool(size_t pos, int toolId, + const wxBitmap& bitmap1, + const wxBitmap& bitmap2 = wxNullBitmap, + bool isToggle = @false, + wxObject* clientData = @NULL, + const wxString& shortHelpString = "", + const wxString& longHelpString = ""); + wxToolBarToolBase * InsertTool(size_t pos, + wxToolBarToolBase* tool); + //@} + + /** + Called when the user clicks on a tool with the left mouse button. + + This is the old way of detecting tool clicks; although it will still work, + you should use the EVT_MENU or EVT_TOOL macro instead. + + @param toolId + The identifier passed to AddTool(). + + @param toggleDown + @true if the tool is a toggle and the toggle is down, otherwise is @false. + + @returns If the tool is a toggle and this function returns @false, the + toggle toggle state (internal and visual) will not be + changed. This provides a way of specifying that + toggle operations are not permitted in some + circumstances. + + @sa OnMouseEnter(), OnRightClick() + */ + bool OnLeftClick(int toolId, bool toggleDown); + + /** + This is called when the mouse cursor moves into a tool or out of + the toolbar. + + This is the old way of detecting mouse enter events; although it will still + work, + you should use the EVT_TOOL_ENTER macro instead. + + @param toolId + Greater than -1 if the mouse cursor has moved into the tool, + or -1 if the mouse cursor has moved. The + programmer can override this to provide extra information about the tool, + such as a short description on the status line. + + @remarks With some derived toolbar classes, if the mouse moves quickly + out of the toolbar, wxWidgets may not be able to + detect it. Therefore this function may not always be + called when expected. + */ + void OnMouseEnter(int toolId); + + /** + Called when the user clicks on a tool with the right mouse button. The + programmer should override this function to detect right tool clicks. + + This is the old way of detecting tool right clicks; although it will still work, + you should use the EVT_TOOL_RCLICKED macro instead. + + @param toolId + The identifier passed to AddTool(). + + @param x + The x position of the mouse cursor. + + @param y + The y position of the mouse cursor. + + @remarks A typical use of this member might be to pop up a menu. + + @sa OnMouseEnter(), OnLeftClick() + */ + void OnRightClick(int toolId, float x, float y); + + /** + This function should be called after you have added tools. + */ + bool Realize(); + + /** + Removes the given tool from the toolbar but doesn't delete it. This allows to + insert/add this tool back to this (or another) toolbar later. + + Note that it is unnecessary to call Realize() for the + change to take place, it will happen immediately. + + @sa DeleteTool() + */ + wxToolBarToolBase * RemoveTool(int id); + + /** + Sets the bitmap resource identifier for specifying tool bitmaps as indices + into a custom bitmap. Windows CE only. + */ + void SetBitmapResource(int resourceId); + + /** + Sets the dropdown menu for the tool given by its @e id. The tool itself will + delete the menu when it's no longer needed. + + If you define a EVT_TOOL_DROPDOWN handler in your program, you must call + wxEvent::Skip from it or the menu won't be displayed. + */ + bool SetDropdownMenu(int id, wxMenu* menu); + + //@{ + /** + Set the values to be used as margins for the toolbar. + + @param size + Margin size. + + @param x + Left margin, right margin and inter-tool separation value. + + @param y + Top margin, bottom margin and inter-tool separation value. + + @remarks This must be called before the tools are added if absolute + positioning is to be used, and the default + (zero-size) margins are to be overridden. + + @sa GetMargins(), wxSize + */ + void SetMargins(const wxSize& size); + void SetMargins(int x, int y); + //@} + + /** + Sets the default size of each tool bitmap. The default bitmap size is 16 by 15 + pixels. + + @param size + The size of the bitmaps in the toolbar. + + @remarks This should be called to tell the toolbar what the tool bitmap + size is. Call it before you add tools. + + @sa GetToolBitmapSize(), GetToolSize() + */ + void SetToolBitmapSize(const wxSize& size); + + /** + Sets the client data associated with the tool. + */ + void SetToolClientData(int id, wxObject* clientData); + + /** + Sets the bitmap to be used by the tool with the given ID when the tool + is in a disabled state. This can only be used on Button tools, not + controls. NOTE: The native toolbar classes on the main platforms all + synthesize the disabled bitmap from the normal bitmap, so this + function will have no effect on those platforms. + */ + void SetToolDisabledBitmap(int id, const wxBitmap& bitmap); + + /** + Sets the long help for the given tool. + + @param toolId + The tool in question. + + @param helpString + A string for the long help. + + @remarks You might use the long help for displaying the tool purpose on + the status line. + + @sa GetToolLongHelp(), SetToolShortHelp(), + */ + void SetToolLongHelp(int toolId, const wxString& helpString); + + /** + Sets the bitmap to be used by the tool with the given ID. This can + only be used on Button tools, not controls. + */ + void SetToolNormalBitmap(int id, const wxBitmap& bitmap); + + /** + Sets the value used for spacing tools. The default value is 1. + + @param packing + The value for packing. + + @remarks The packing is used for spacing in the vertical direction if the + toolbar is horizontal, and for spacing in the + horizontal direction if the toolbar is vertical. + + @sa GetToolPacking() + */ + void SetToolPacking(int packing); + + /** + Sets the default separator size. The default value is 5. + + @param separation + The separator size. + + @sa AddSeparator() + */ + void SetToolSeparation(int separation); + + /** + Sets the short help for the given tool. + + @param toolId + The tool in question. + + @param helpString + The string for the short help. + + @remarks An application might use short help for identifying the tool + purpose in a tooltip. + + @sa GetToolShortHelp(), SetToolLongHelp() + */ + void SetToolShortHelp(int toolId, const wxString& helpString); + + /** + Toggles a tool on or off. This does not cause any event to get emitted. + + @param toolId + Tool in question. + + @param toggle + If @true, toggles the tool on, otherwise toggles it off. + + @remarks Only applies to a tool that has been specified as a toggle tool. + */ + void ToggleTool(int toolId, bool toggle); +}; diff --git a/interface/toolbook.h b/interface/toolbook.h new file mode 100644 index 0000000000..331bdece6c --- /dev/null +++ b/interface/toolbook.h @@ -0,0 +1,43 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: toolbook.h +// Purpose: documentation for wxToolbook class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxToolbook + @wxheader{toolbook.h} + + wxToolbook is a class similar to wxNotebook but which + uses a wxToolBar to show the labels instead of the + tabs. + + There is no documentation for this class yet but its usage is + identical to wxNotebook (except for the features clearly related to tabs + only), so please refer to that class documentation for now. You can also + use the @ref overview_samplenotebook "notebook sample" to see wxToolbook in + action. + + @beginStyleTable + @style{wxTBK_BUTTONBAR}: + Use wxButtonToolBar-based implementation under Mac OS (ignored + under other platforms.) + @style{wxTBK_HORZ_LAYOUT}: + Shows the text and the icons alongside, not vertically stacked + (only implement under Windows and GTK 2 platforms as it relies on + wxTB_HORZ_LAYOUT flag support). + @endStyleTable + + @library{wxcore} + @category{FIXME} + + @seealso + wxBookCtrl, wxNotebook, @ref overview_samplenotebook "notebook sample" +*/ +class wxToolbook : public wxBookCtrl overview +{ +public: + +}; diff --git a/interface/tooltip.h b/interface/tooltip.h new file mode 100644 index 0000000000..63215ba3d1 --- /dev/null +++ b/interface/tooltip.h @@ -0,0 +1,74 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tooltip.h +// Purpose: documentation for wxToolTip class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxToolTip + @wxheader{tooltip.h} + + This class holds information about a tooltip associated with a window + (see wxWindow::SetToolTip). + + The four static methods, wxToolTip::Enable, + wxToolTip::SetDelay + wxToolTip::SetAutoPop and + wxToolTip::SetReshow can be used to globally + alter tooltips behaviour. + + @library{wxcore} + @category{help} +*/ +class wxToolTip : public wxObject +{ +public: + /** + Constructor. + */ + wxToolTip(const wxString& tip); + + /** + Enable or disable tooltips globally. + + May not be supported on all platforms (eg. wxCocoa). + */ + static void Enable(bool flag); + + /** + Get the tooltip text. + */ + wxString GetTip(); + + /** + Get the associated window. + */ + wxWindow* GetWindow(); + + /** + Set the delay after which the tooltip disappears or how long a + tooltip remains visible. + May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). + */ + static void SetAutoPop(long msecs); + + /** + Set the delay after which the tooltip appears. + + May not be supported on all platforms (eg. wxCocoa). + */ + static void SetDelay(long msecs); + + /** + Set the delay between subsequent tooltips to appear. + May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). + */ + static void SetReshow(long msecs); + + /** + Set the tooltip text. + */ + void SetTip(const wxString& tip); +}; diff --git a/interface/toplevel.h b/interface/toplevel.h new file mode 100644 index 0000000000..ac138306a8 --- /dev/null +++ b/interface/toplevel.h @@ -0,0 +1,385 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: toplevel.h +// Purpose: documentation for wxTopLevelWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTopLevelWindow + @wxheader{toplevel.h} + + wxTopLevelWindow is a common base class for wxDialog and + wxFrame. It is an abstract base class meaning that you never + work with objects of this class directly, but all of its methods are also + applicable for the two classes above. + + @library{wxcore} + @category{managedwnd} + + @seealso + wxTopLevelWindow::SetTransparent +*/ +class wxTopLevelWindow : public wxWindow +{ +public: + /** + Returns @true if the platform supports making the window translucent. + + @sa SetTransparent() + */ + virtual bool CanSetTransparent(); + + /** + A synonym for CentreOnScreen(). + */ + void CenterOnScreen(int direction); + + /** + Centres the window on screen. + + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. + + @sa wxWindow::CentreOnParent + */ + void CentreOnScreen(int direction = wxBOTH); + + /** + Enables or disables the Close button (most often in the right + upper corner of a dialog) and the Close entry of the system + menu (most often in the left upper corner of the dialog). + Currently only implemented for wxMSW and wxGTK. Returns + @true if operation was successful. This may be wrong on + X11 (including GTK+) where the window manager may not support + this operation and there is no way to find out. + */ + bool EnableCloseButton(bool enable = @true); + + /** + Returns a pointer to the button which is the default for this window, or @c + @NULL. + The default button is the one activated by pressing the Enter key. + */ + wxWindow * GetDefaultItem(); + + /** + Returns the standard icon of the window. The icon will be invalid if it hadn't + been previously set by SetIcon(). + + @sa GetIcons() + */ + const wxIcon GetIcon(); + + /** + Returns all icons associated with the window, there will be none of them if + neither SetIcon() nor + SetIcons() had been called before. + + Use GetIcon() to get the main icon of the + window. + + @sa wxIconBundle + */ + const wxIconBundle GetIcons(); + + /** + Gets a string containing the window title. + + @sa SetTitle() + */ + wxString GetTitle(); + + /** + Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input panel) + area and resize + window accordingly. Override this if you want to avoid resizing or do additional + operations. + */ + virtual bool HandleSettingChange(WXWPARAM wParam, + WXLPARAM lParam); + + /** + Iconizes or restores the window. + + @param iconize + If @true, iconizes the window; if @false, shows and restores it. + + @sa IsIconized(), Maximize(). + */ + void Iconize(bool iconize); + + /** + Returns @true if this window is currently active, i.e. if the user is + currently + working with it. + */ + bool IsActive(); + + /** + Returns @true if this window is expected to be always maximized, either due + to platform policy + or due to local policy regarding particular class. + */ + virtual bool IsAlwaysMaximized(); + + /** + Returns @true if the window is in fullscreen mode. + + @sa ShowFullScreen() + */ + bool IsFullScreen(); + + /** + Returns @true if the window is iconized. + */ + bool IsIconized(); + + /** + Returns @true if the window is maximized. + */ + bool IsMaximized(); + + /** + @b @c This method is specific to wxUniversal port + + Returns @true if this window is using native decorations, @false if we draw + them ourselves. + + @sa UseNativeDecorations(), + UseNativeDecorationsByDefault() + */ + bool IsUsingNativeDecorations(); + + /** + Maximizes or restores the window. + + @param maximize + If @true, maximizes the window, otherwise it restores it. + + @sa Iconize() + */ + void Maximize(bool maximize); + + /** + Use a system-dependent way to attract users attention to the window when it is + in background. + + @e flags may have the value of either @c wxUSER_ATTENTION_INFO + (default) or @c wxUSER_ATTENTION_ERROR which results in a more drastic + action. When in doubt, use the default value. + + Note that this function should normally be only used when the application is + not already in foreground. + + This function is currently implemented for Win32 where it flashes the + window icon in the taskbar, and for wxGTK with task bars supporting it. + */ + void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO); + + /** + Changes the default item for the panel, usually @e win is a button. + + @sa GetDefaultItem() + */ + void SetDefaultItem(wxWindow win); + + /** + Sets the icon for this window. + + @param icon + The icon to associate with this window. + + @remarks The window takes a 'copy' of icon, but since it uses reference + counting, the copy is very quick. It is safe to + delete icon after calling this function. + */ + void SetIcon(const wxIcon& icon); + + /** + Sets several icons of different sizes for this window: this allows to use + different icons for different situations (e.g. task switching bar, taskbar, + window title bar) instead of scaling, with possibly bad looking results, the + only icon set by SetIcon(). + + @param icons + The icons to associate with this window. + + @sa wxIconBundle. + */ + void SetIcons(const wxIconBundle& icons); + + /** + Sets action or menu activated by pressing left hardware button on the smart + phones. + Unavailable on full keyboard machines. + + @param id + Identifier for this button. + + @param label + Text to be displayed on the screen area dedicated to this hardware button. + + @param subMenu + The menu to be opened after pressing this hardware button. + + @sa SetRightMenu(). + */ + void SetLeftMenu(int id = wxID_ANY, + const wxString& label = wxEmptyString, + wxMenu * subMenu = @NULL); + + /** + A simpler interface for setting the size hints than + SetSizeHints(). + */ + void SetMaxSize(const wxSize& size); + + /** + A simpler interface for setting the size hints than + SetSizeHints(). + */ + void SetMinSize(const wxSize& size); + + /** + Sets action or menu activated by pressing right hardware button on the smart + phones. + Unavailable on full keyboard machines. + + @param id + Identifier for this button. + + @param label + Text to be displayed on the screen area dedicated to this hardware button. + + @param subMenu + The menu to be opened after pressing this hardware button. + + @sa SetLeftMenu(). + */ + void SetRightMenu(int id = wxID_ANY, + const wxString& label = wxEmptyString, + wxMenu * subMenu = @NULL); + + /** + If the platform supports it, sets the shape of the window to that + depicted by @e region. The system will not display or + respond to any mouse event for the pixels that lie outside of the + region. To reset the window to the normal rectangular shape simply + call @e SetShape again with an empty region. Returns @true if the + operation is successful. + */ + bool SetShape(const wxRegion& region); + + //@{ + /** + Allows specification of minimum and maximum window sizes, and window size + increments. + If a pair of values is not set (or set to -1), no constraints will be used. + + @param incW + Specifies the increment for sizing the width (GTK/Motif/Xt only). + + @param incH + Specifies the increment for sizing the height (GTK/Motif/Xt only). + + @param incSize + Increment size (only taken into account under X11-based + ports such as wxGTK/wxMotif/wxX11). + + @remarks Notice that this function not only prevents the user from + resizing the window outside the given bounds but it + also prevents the program itself from doing it using + SetSize. + */ + virtual void SetSizeHints(int minW, int minH, int maxW=-1, + int maxH=-1, + int incW=-1, + int incH=-1); + void SetSizeHints(const wxSize& minSize, + const wxSize& maxSize=wxDefaultSize, + const wxSize& incSize=wxDefaultSize); + //@} + + /** + Sets the window title. + + @param title + The window title. + + @sa GetTitle() + */ + virtual void SetTitle(const wxString& title); + + /** + If the platform supports it will set the window to be translucent + + @param alpha + Determines how opaque or transparent the window will + be, if the platform supports the opreration. A value of 0 sets the + window to be fully transparent, and a value of 255 sets the window + to be fully opaque. + */ + virtual bool SetTransparent(int alpha); + + /** + This virtual function is not meant to be called directly but can be overridden + to return @false (it returns @true by default) to allow the application to + close even if this, presumably not very important, window is still opened. + By default, the application stays alive as long as there are any open top level + windows. + */ + virtual bool ShouldPreventAppExit(); + + /** + Depending on the value of @e show parameter the window is either shown full + screen or restored to its normal state. @e style is a bit list containing + some or all of the following values, which indicate what elements of the window + to hide in full-screen mode: + + wxFULLSCREEN_NOMENUBAR + wxFULLSCREEN_NOTOOLBAR + wxFULLSCREEN_NOSTATUSBAR + wxFULLSCREEN_NOBORDER + wxFULLSCREEN_NOCAPTION + wxFULLSCREEN_ALL (all of the above) + + This function has not been tested with MDI frames. + + Note that showing a window full screen also actually + @ref wxWindow::show Show()s if it hadn't been shown yet. + + @sa IsFullScreen() + */ + bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL); + + /** + @b @c This method is specific to wxUniversal port + + Use native or custom-drawn decorations for this window only. Notice that to + have any effect this method must be called before really creating the window, + i.e. two step creation must be used: + + @sa UseNativeDecorationsByDefault(), + IsUsingNativeDecorations() + */ + void UseNativeDecorations(bool native = @true); + + /** + @b @c This method is specific to wxUniversal port + + Top level windows in wxUniversal port can use either system-provided window + decorations (i.e. title bar and various icons, buttons and menus in it) or draw + the decorations themselves. By default the system decorations are used if they + are available, but this method can be called with @e native set to @false to + change this for all windows created after this point. + + Also note that if @c WXDECOR environment variable is set, then custom + decorations are used by default and so it may make sense to call this method + with default argument if the application can't use custom decorations at all + for some reason. + */ + void UseNativeDecorationsByDefault(bool native = @true); +}; diff --git a/interface/tracker.h b/interface/tracker.h new file mode 100644 index 0000000000..7c4e02f1c5 --- /dev/null +++ b/interface/tracker.h @@ -0,0 +1,37 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tracker.h +// Purpose: documentation for wxTrackable class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTrackable + @wxheader{tracker.h} + + Add-on base class for a trackable object. This class maintains + an internal linked list of classes of type wxTrackerNode and + calls OnObjectDestroy() on them if this object is destroyed. + The most common usage is by using the wxWeakRefT + class template which automates this. This class has no public + API. Its only use is by deriving another class from it to + make it trackable. + + @code + class MyClass: public Foo, public wxTrackable + { + // whatever + } + + typedef wxWeakRefMyClass MyClassRef; + @endcode + + @library{wxbase} + @category{FIXME} +*/ +class wxTrackable +{ +public: + +}; diff --git a/interface/treebase.h b/interface/treebase.h new file mode 100644 index 0000000000..02618e84b0 --- /dev/null +++ b/interface/treebase.h @@ -0,0 +1,45 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: treebase.h +// Purpose: documentation for wxTreeItemId class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTreeItemId + @wxheader{treebase.h} + + An opaque reference to a tree item. + + @library{wxcore} + @category{FIXME} + + @seealso + wxTreeCtrl, wxTreeItemData, @ref overview_wxtreectrloverview "wxTreeCtrl + overview" +*/ +class wxTreeItemId +{ +public: + /** + Default constructor. wxTreemItemIds are not meant to be constructed explicitly + by + the user; they are returned by the wxTreeCtrl functions instead. + */ + wxTreeItemId(); + + /** + Returns @true if this instance is referencing a valid tree item. + */ +#define bool IsOk() /* implementation is private */ + + //@{ + /** + Operators for comparison between wxTreeItemId objects. + */ + void operator !(); + bool operator ==(const wxTreeItemId& item); + bool operator !=(const wxTreeItemId& item); + //@} +}; diff --git a/interface/treebook.h b/interface/treebook.h new file mode 100644 index 0000000000..f4502af7a5 --- /dev/null +++ b/interface/treebook.h @@ -0,0 +1,268 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: treebook.h +// Purpose: documentation for wxTreebookEvent class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTreebookEvent + @wxheader{treebook.h} + + This class represents the events generated by a treebook control: currently, + there are four of them. The PAGE_CHANGING and PAGE_CHANGED - have exactly the + same + behaviour as wxNotebookEvent. + + The other two NODE_COLLAPSED and NODE_EXPANDED are triggered when page node in + the tree control + is collapsed/expanded. The page index could be retreived by calling + wxTreebookEvent::GetSelection. + + + @library{wxcore} + @category{events} + + @seealso + wxNotebookEvent, wxTreebook +*/ +class wxTreebookEvent : public wxNotifyEvent +{ +public: + /** + @sa wxNotebookEvent + */ + wxTreebookEvent(wxEventType commandType = wxEVT_@NULL, int id = 0, + int nSel = wxNOT_FOUND, + int nOldSel = wxNOT_FOUND); + + /** + Returns the page that was selected before the change, wxNOT_FOUND if none was + selected. + */ + int GetOldSelection(); + + /** + Returns the currently selected page, or wxNOT_FOUND if none was selected. + */ + int GetSelection(); +}; + + +/** + @class wxTreebook + @wxheader{treebook.h} + + This class is an extension of the Notebook class that allows a tree structured + set of pages to be shown in a control. + A classic example is a netscape preferences dialog that shows a tree + of preference sections on the left and select section page on the right. + + To use the class simply create it and populate with pages using + wxTreebook::InsertPage, + wxTreebook::InsertSubPage, + wxTreebook::AddPage, + wxTreebook::AddSubPage. + + If your tree is no more than 1 level in depth then you could + simply use wxTreebook::AddPage and + wxTreebook::AddSubPage to sequentially populate your tree + by adding at every step a page or a subpage to the end of the tree. + + @library{wxcore} + @category{miscwnd} + + @seealso + wxNotebook, wxTreebookEvent, wxImageList, @ref overview_samplenotebook + "notebook sample" +*/ +class wxTreebook : public wxBookCtrl overview +{ +public: + //@{ + /** + Creates an empty TreeBook control. + + @param parent + The parent window. Must be non-@NULL. + + @param id + The window identifier. + + @param pos + The window position. + + @param size + The window size. + + @param style + The window style. See wxNotebook. + + @param name + The name of the control (used only under Motif). + */ + wxTreebook(); + wxTreebook(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTBK_DEFAULT, + const wxString& name = wxEmptyString); + //@} + + /** + Destroys the wxTreebook object. + + Also deletes all the pages owned by the control (inserted previously into it). + */ + ~wxTreebook(); + + /** + Adds a new page. The page is placed at the topmost level after all other pages. + @NULL could be specified for page to create an empty page. + */ + bool AddPage(wxWindow* page, const wxString& text, + bool bSelect = @false, + int imageId = wxNOT_FOUND); + + /** + Adds a new child-page to the last top-level page. + @NULL could be specified for page to create an empty page. + */ + bool AddSubPage(wxWindow* page, const wxString& text, + bool bSelect = @false, + int imageId = wxNOT_FOUND); + + /** + Sets the image list for the page control and takes ownership of the list. + + @sa wxImageList, SetImageList() + */ + void AssignImageList(wxImageList* imageList); + + /** + Changes the selection for the given page, returning the previous selection. + + The call to this function does not generate the page changing events. + This is the only difference with SetSelection(). + See @ref overview_progevent "this topic" for more info. + */ + int ChangeSelection(size_t page); + + /** + Shortcut for wxTreebook::ExpandNode(pageId, @false). + */ + bool CollapseNode(size_t pageId); + + /** + Creates a treebook control. See wxTreebook() for the description of the + parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTBK_DEFAULT, + const wxString& name = wxEmptyString); + + /** + Deletes all pages inserted into the treebook. No event is generated. + */ + bool DeleteAllPages(); + + /** + Deletes the page at the specified position and all its children. Could trigger + page selection change + in a case when selected page is removed. In that case its parent is selected + (or the next page if no parent). + */ + bool DeletePage(size_t pagePos); + + /** + Expands (collapses) the pageId node. Returns the previous state. + May generate page changing events (if selected page + is under the collapsed branch, then its parent is autoselected). + */ + bool ExpandNode(size_t pageId, bool expand = @true); + + /** + Returns the image index for the given page. + */ + int GetPageImage(size_t n); + + /** + Returns the parent page of the given one or @c wxNOT_FOUND if this is a + top-level page. + */ + int GetPageParent(size_t page); + + /** + Returns the string for the given page. + */ + wxString GetPageText(size_t n); + + /** + Returns the currently selected page, or wxNOT_FOUND if none was selected. + + Note that this method may return either the previously or newly selected page + when called from the EVT_TREEBOOK_PAGE_CHANGED handler + depending on the platform and so wxTreebookEvent::GetSelection should be used + instead in this case. + */ + int GetSelection(); + + /** + Inserts a new page just before the page indicated by pagePos. + The new page is placed before pagePos page and on the same level. + @NULL could be specified for page to create an empty page. + */ + bool InsertPage(size_t pagePos, wxWindow* page, + const wxString& text, + bool bSelect = @false, + int imageId = wxNOT_FOUND); + + /** + Inserts a sub page under the specified page. + + @NULL could be specified for page to create an empty page. + */ + bool InsertSubPage(size_t pagePos, wxWindow* page, + const wxString& text, + bool bSelect = @false, + int imageId = wxNOT_FOUND); + + /** + Gets the pagePos page state -- whether it is expanded or collapsed + */ + bool IsNodeExpanded(size_t pageId); + + /** + Sets the image list for the page control. It does not take ownership of the + image list, you must delete it yourself. + + @sa wxImageList, AssignImageList() + */ + void SetImageList(wxImageList* imageList); + + /** + Sets the image index for the given page. ImageId is an index into the image list + which was set with SetImageList(). + */ + bool SetPageImage(size_t page, int imageId); + + /** + Sets the text for the given page. + */ + bool SetPageText(size_t page, const wxString& text); + + /** + Sets the selection for the given page, returning the previous selection. + + The call to this function generates the page changing events. + + This function is deprecated and should not be used in new code. Please use the + ChangeSelection() function instead. + + @sa GetSelection() + */ + int SetSelection(size_t n); +}; diff --git a/interface/treectrl.h b/interface/treectrl.h new file mode 100644 index 0000000000..5840f2a759 --- /dev/null +++ b/interface/treectrl.h @@ -0,0 +1,999 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: treectrl.h +// Purpose: documentation for wxTreeItemData class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTreeItemData + @wxheader{treectrl.h} + + wxTreeItemData is some (arbitrary) user class associated with some item. The + main advantage of having this class is that wxTreeItemData objects are + destroyed automatically by the tree and, as this class has virtual destructor, + it means that the memory and any other resources associated with a tree item + will be automatically freed when it is deleted. Note that we don't use wxObject + as the base class for wxTreeItemData because the size of this class is + critical: in many applications, each tree leaf will have wxTreeItemData + associated with it and the number of leaves may be quite big. + + Also please note that because the objects of this class are deleted by the tree + using the operator @c delete, they must always be allocated on the heap + using @c new. + + @library{wxcore} + @category{FIXME} + + @seealso + wxTreeCtrl +*/ +class wxTreeItemData : public wxClientData +{ +public: + /** + Default constructor. + In addition, the following methods are added in wxPython for accessing + the object: + + + + @b GetData() + + + Returns a reference to the Python Object + + @b SetData(obj) + + + Associates a new Python Object with the + wxTreeItemData + */ + wxTreeItemData(); + + /** + Virtual destructor. + */ + ~wxTreeItemData(); + + /** + Returns the item associated with this node. + */ + const wxTreeItemId GetId(); + + /** + Sets the item associated with this node. + */ + void SetId(const wxTreeItemId& id); +}; + + +/** + @class wxTreeCtrl + @wxheader{treectrl.h} + + A tree control presents information as a hierarchy, with items that may be + expanded + to show further items. Items in a tree control are referenced by wxTreeItemId + handles, + which may be tested for validity by calling wxTreeItemId::IsOk. + + To intercept events from a tree control, use the event table macros described + in wxTreeEvent. + + @beginStyleTable + @style{wxTR_EDIT_LABELS}: + Use this style if you wish the user to be able to edit labels in + the tree control. + @style{wxTR_NO_BUTTONS}: + For convenience to document that no buttons are to be drawn. + @style{wxTR_HAS_BUTTONS}: + Use this style to show + and - buttons to the left of parent items. + @style{wxTR_NO_LINES}: + Use this style to hide vertical level connectors. + @style{wxTR_FULL_ROW_HIGHLIGHT}: + Use this style to have the background colour and the selection + highlight extend over the entire horizontal row of the tree control + window. (This flag is ignored under Windows unless you specify + wxTR_NO_LINES as well.) + @style{wxTR_LINES_AT_ROOT}: + Use this style to show lines between root nodes. Only applicable if + wxTR_HIDE_ROOT is set and wxTR_NO_LINES is not set. + @style{wxTR_HIDE_ROOT}: + Use this style to suppress the display of the root node, + effectively causing the first-level nodes to appear as a series of + root nodes. + @style{wxTR_ROW_LINES}: + Use this style to draw a contrasting border between displayed rows. + @style{wxTR_HAS_VARIABLE_ROW_HEIGHT}: + Use this style to cause row heights to be just big enough to fit + the content. If not set, all rows use the largest row height. The + default is that this flag is unset. Generic only. + @style{wxTR_SINGLE}: + For convenience to document that only one item may be selected at a + time. Selecting another item causes the current selection, if any, + to be deselected. This is the default. + @style{wxTR_MULTIPLE}: + Use this style to allow a range of items to be selected. If a + second range is selected, the current range, if any, is deselected. + @style{wxTR_DEFAULT_STYLE}: + The set of flags that are closest to the defaults for the native + control for a particular toolkit. + @endStyleTable + + @library{wxcore} + @category{ctrl} + @appearance{treectrl.png} + + @seealso + wxTreeItemData, @ref overview_wxtreectrloverview "wxTreeCtrl overview", + wxListBox, wxListCtrl, wxImageList, wxTreeEvent +*/ +class wxTreeCtrl : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a tree control. + + @param parent + Parent window. Must not be @NULL. + + @param id + Window identifier. The value wxID_ANY indicates a default value. + + @param pos + Window position. + + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + + @param style + Window style. See wxTreeCtrl. + + @param validator + Window validator. + + @param name + Window name. + + @sa Create(), wxValidator + */ + wxTreeCtrl(); + wxTreeCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTR_HAS_BUTTONS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "treeCtrl"); + //@} + + /** + Destructor, destroying the tree control. + */ + ~wxTreeCtrl(); + + /** + Adds the root node to the tree, returning the new item. + + The @e image and @e selImage parameters are an index within + the normal image list specifying the image to use for unselected and + selected items, respectively. + If @e image -1 and @e selImage is -1, the same image is used for + both selected and unselected items. + */ + wxTreeItemId AddRoot(const wxString& text, int image = -1, + int selImage = -1, + wxTreeItemData* data = @NULL); + + /** + Appends an item to the end of the branch identified by @e parent, return a new + item id. + + The @e image and @e selImage parameters are an index within + the normal image list specifying the image to use for unselected and + selected items, respectively. + If @e image -1 and @e selImage is -1, the same image is used for + both selected and unselected items. + */ + wxTreeItemId AppendItem(const wxTreeItemId& parent, + const wxString& text, + int image = -1, + int selImage = -1, + wxTreeItemData* data = @NULL); + + /** + Sets the buttons image list. The button images assigned with this method will + be automatically deleted by wxTreeCtrl as appropriate + (i.e. it takes ownership of the list). + + Setting or assigning the button image list enables the display of image buttons. + Once enabled, the only way to disable the display of button images is to set + the button image list to @NULL. + + This function is only available in the generic version. + + See also SetButtonsImageList(). + */ + void AssignButtonsImageList(wxImageList* imageList); + + /** + Sets the normal image list. Image list assigned with this method will + be automatically deleted by wxTreeCtrl as appropriate + (i.e. it takes ownership of the list). + + See also SetImageList(). + */ + void AssignImageList(wxImageList* imageList); + + /** + Sets the state image list. Image list assigned with this method will + be automatically deleted by wxTreeCtrl as appropriate + (i.e. it takes ownership of the list). + + See also SetStateImageList(). + */ + void AssignStateImageList(wxImageList* imageList); + + /** + Collapses the given item. + */ + void Collapse(const wxTreeItemId& item); + + /** + Collapses the root item. + + @sa ExpandAll() + */ + void CollapseAll(); + + /** + Collapses this item and all of its children, recursively. + + @sa ExpandAllChildren() + */ + void CollapseAllChildren(const wxTreeItemId& item); + + /** + Collapses the given item and removes all children. + */ + void CollapseAndReset(const wxTreeItemId& item); + + /** + Creates the tree control. See wxTreeCtrl() for further details. + */ + bool wxTreeCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTR_HAS_BUTTONS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "treeCtrl"); + + /** + Deletes the specified item. A @c EVT_TREE_DELETE_ITEM event will be + generated. + + This function may cause a subsequent call to GetNextChild to fail. + */ + void Delete(const wxTreeItemId& item); + + /** + Deletes all items in the control. Note that this may not generate + @c EVT_TREE_DELETE_ITEM events under some Windows versions although + normally such event is generated for each removed item. + */ + void DeleteAllItems(); + + /** + Deletes all children of the given item (but not the item itself). Note that + this will @b not generate any events unlike + Delete() method. + + If you have called SetItemHasChildren(), you + may need to call it again since @e DeleteChildren does not automatically + clear the setting. + */ + void DeleteChildren(const wxTreeItemId& item); + + /** + Starts editing the label of the given item. This function generates a + EVT_TREE_BEGIN_LABEL_EDIT event which can be vetoed so that no + text control will appear for in-place editing. + + If the user changed the label (i.e. s/he does not press ESC or leave + the text control without changes, a EVT_TREE_END_LABEL_EDIT event + will be sent which can be vetoed as well. + + @sa EndEditLabel(), wxTreeEvent + */ + void EditLabel(const wxTreeItemId& item); + + /** + Ends label editing. If @e cancelEdit is @true, the edit will be cancelled. + + This function is currently supported under Windows only. + + @sa EditLabel() + */ + void EndEditLabel(bool cancelEdit); + + /** + Scrolls and/or expands items to ensure that the given item is visible. + */ + void EnsureVisible(const wxTreeItemId& item); + + /** + Expands the given item. + */ + void Expand(const wxTreeItemId& item); + + /** + Expands all items in the tree. + */ + void ExpandAll(); + + /** + Expands the given item and all its children recursively. + */ + void ExpandAllChildren(const wxTreeItemId& item); + + /** + Retrieves the rectangle bounding the @e item. If @e textOnly is @true, + only the rectangle around the item's label will be returned, otherwise the + item's image is also taken into account. + + The return value is @true if the rectangle was successfully retrieved or @c + @false + if it was not (in this case @e rect is not changed) -- for example, if the + item is currently invisible. + + Notice that the rectangle coordinates are logical, not physical ones. So, for + example, the x coordinate may be negative if the tree has a horizontal + scrollbar and its position is not 0. + */ + bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect, + bool textOnly = @false); + + /** + Returns the buttons image list (from which application-defined button images + are taken). + + This function is only available in the generic version. + */ + wxImageList* GetButtonsImageList(); + + /** + Returns the number of items in the branch. If @e recursively is @true, + returns the total number + of descendants, otherwise only one level of children is counted. + */ + unsigned int GetChildrenCount(const wxTreeItemId& item, + bool recursively = @true); + + /** + Returns the number of items in the control. + */ + unsigned int GetCount(); + + /** + Returns the edit control being currently used to edit a label. Returns @NULL + if no label is being edited. + + @b NB: It is currently only implemented for wxMSW. + */ + wxTextCtrl * GetEditControl(); + + /** + Returns the first child; call GetNextChild() for the next child. + + For this enumeration function you must pass in a 'cookie' parameter + which is opaque for the application but is necessary for the library + to make these functions reentrant (i.e. allow more than one + enumeration on one and the same object simultaneously). The cookie passed to + GetFirstChild and GetNextChild should be the same variable. + + Returns an invalid tree item (i.e. IsOk() returns @false) if there are no + further children. + + @sa GetNextChild(), GetNextSibling() + */ + wxTreeItemId GetFirstChild(const wxTreeItemId& item, + wxTreeItemIdValue & cookie); + + /** + Returns the first visible item. + */ + wxTreeItemId GetFirstVisibleItem(); + + /** + Returns the normal image list. + */ + wxImageList* GetImageList(); + + /** + Returns the current tree control indentation. + */ + int GetIndent(); + + /** + Returns the background colour of the item. + */ + wxColour GetItemBackgroundColour(const wxTreeItemId& item); + + //@{ + /** + Returns the font of the item label. + */ + wxTreeItemData* GetItemData(const wxTreeItemId& item); + See also wxPython note: wxPython provides the following shortcut method: + + + + + + + +GetPyData(item) + + + + +Returns the Python Object +associated with the wxTreeItemData for the given item Id. + + + + + + + +wxFont GetItemFont(const wxTreeItemId& item); + //@} + + /** + Gets the specified item image. The value of @e which may be: + + wxTreeItemIcon_Normal to get the normal item image + wxTreeItemIcon_Selected to get the selected item image (i.e. the image + which is shown when the item is currently selected) + wxTreeItemIcon_Expanded to get the expanded image (this only + makes sense for items which have children - then this image is shown when the + item is expanded and the normal image is shown when it is collapsed) + wxTreeItemIcon_SelectedExpanded to get the selected expanded image + (which is shown when an expanded item is currently selected) + */ + int GetItemImage(const wxTreeItemId& item, + wxTreeItemIcon which = wxTreeItemIcon_Normal); + + /** + Returns the item's parent. + */ + wxTreeItemId GetItemParent(const wxTreeItemId& item); + + /** + Gets the selected item image (this function is obsolete, use + @c GetItemImage(item, wxTreeItemIcon_Selected) instead). + */ + int GetItemSelectedImage(const wxTreeItemId& item); + + /** + Returns the item label. + */ + wxString GetItemText(const wxTreeItemId& item); + + /** + Returns the colour of the item label. + */ + wxColour GetItemTextColour(const wxTreeItemId& item); + + /** + Returns the last child of the item (or an invalid tree item if this item has no + children). + + @sa GetFirstChild(), GetNextSibling(), + GetLastChild() + */ + wxTreeItemId GetLastChild(const wxTreeItemId& item); + + /** + Returns the next child; call GetFirstChild() for the first child. + + For this enumeration function you must pass in a 'cookie' parameter + which is opaque for the application but is necessary for the library + to make these functions reentrant (i.e. allow more than one + enumeration on one and the same object simultaneously). The cookie passed to + GetFirstChild and GetNextChild should be the same. + + Returns an invalid tree item if there are no further children. + + @sa GetFirstChild() + */ + wxTreeItemId GetNextChild(const wxTreeItemId& item, + wxTreeItemIdValue & cookie); + + /** + Returns the next sibling of the specified item; call GetPrevSibling() for the + previous sibling. + + Returns an invalid tree item if there are no further siblings. + + @sa GetPrevSibling() + */ + wxTreeItemId GetNextSibling(const wxTreeItemId& item); + + /** + Returns the next visible item or an invalid item if this item is the last + visible one. + + Notice that the @e item itself must be visible. + */ + wxTreeItemId GetNextVisible(const wxTreeItemId& item); + + /** + Returns the previous sibling of the specified item; call GetNextSibling() for + the next sibling. + + Returns an invalid tree item if there are no further children. + + @sa GetNextSibling() + */ + wxTreeItemId GetPrevSibling(const wxTreeItemId& item); + + /** + Returns the previous visible item or an invalid item if this item is the first + visible one. + + Notice that the @e item itself must be visible. + */ + wxTreeItemId GetPrevVisible(const wxTreeItemId& item); + + /** + Returns @true if the control will use a quick calculation for the best size, + looking only at the first and last items. The default is @false. + + @sa SetQuickBestSize() + */ + bool GetQuickBestSize(); + + /** + Returns the root item for the tree control. + */ + wxTreeItemId GetRootItem(); + + /** + Returns the selection, or an invalid item if there is no selection. + This function only works with the controls without wxTR_MULTIPLE style, use + GetSelections() for the controls which do have + this style. + */ + wxTreeItemId GetSelection(); + + /** + Fills the array of tree items passed in with the currently selected items. This + function can be called only if the control has the wxTR_MULTIPLE style. + + Returns the number of selected items. + */ + unsigned int GetSelections(wxArrayTreeItemIds& selection); + + /** + Returns the state image list (from which application-defined state images are + taken). + */ + wxImageList* GetStateImageList(); + + /** + Calculates which (if any) item is under the given point, returning the tree item + id at this point plus extra information @e flags. @e flags is a bitlist of the + following: + + + wxTREE_HITTEST_ABOVE + + + Above the client area. + + wxTREE_HITTEST_BELOW + + + Below the client area. + + wxTREE_HITTEST_NOWHERE + + + In the client area but below the last item. + + wxTREE_HITTEST_ONITEMBUTTON + + + On the button associated with an item. + + wxTREE_HITTEST_ONITEMICON + + + On the bitmap associated with an item. + + wxTREE_HITTEST_ONITEMINDENT + + + In the indentation associated with an item. + + wxTREE_HITTEST_ONITEMLABEL + + + On the label (string) associated with an item. + + wxTREE_HITTEST_ONITEMRIGHT + + + In the area to the right of an item. + + wxTREE_HITTEST_ONITEMSTATEICON + + + On the state icon for a tree view item that is in a user-defined state. + + wxTREE_HITTEST_TOLEFT + + + To the right of the client area. + + wxTREE_HITTEST_TORIGHT + + + To the left of the client area. + */ + wxTreeItemId HitTest(const wxPoint& point, int& flags); + + //@{ + /** + Inserts an item after a given one (@e previous) or before one identified by its + position (@e before). + @e before must be less than the number of children. + + The @e image and @e selImage parameters are an index within + the normal image list specifying the image to use for unselected and + selected items, respectively. + If @e image -1 and @e selImage is -1, the same image is used for + both selected and unselected items. + */ + wxTreeItemId InsertItem(const wxTreeItemId& parent, + const wxTreeItemId& previous, + const wxString& text, + int image = -1, + int selImage = -1, + wxTreeItemData* data = @NULL); + wxTreeItemId InsertItem(const wxTreeItemId& parent, + size_t before, + const wxString& text, + int image = -1, + int selImage = -1, + wxTreeItemData* data = @NULL); + //@} + + /** + Returns @true if the given item is in bold state. + + See also: SetItemBold() + */ + bool IsBold(const wxTreeItemId& item); + + /** + Returns @true if the control is empty (i.e. has no items, even no root one). + */ + bool IsEmpty(); + + /** + Returns @true if the item is expanded (only makes sense if it has children). + */ + bool IsExpanded(const wxTreeItemId& item); + + /** + Returns @true if the item is selected. + */ + bool IsSelected(const wxTreeItemId& item); + + /** + Returns @true if the item is visible on the screen. + */ + bool IsVisible(const wxTreeItemId& item); + + /** + Returns @true if the item has children. + */ + bool ItemHasChildren(const wxTreeItemId& item); + + /** + Override this function in the derived class to change the sort order of the + items in the tree control. The function should return a negative, zero or + positive value if the first item is less than, equal to or greater than the + second one. + + Please note that you @b must use wxRTTI macros + DECLARE_DYNAMIC_CLASS and + IMPLEMENT_DYNAMIC_CLASS if you override this + function because otherwise the base class considers that it is not overridden + and uses the default comparison, i.e. sorts the items alphabetically, which + allows it optimize away the calls to the virtual function completely. + + See also: SortChildren() + */ + int OnCompareItems(const wxTreeItemId& item1, + const wxTreeItemId& item2); + + /** + Appends an item as the first child of @e parent, return a new item id. + + The @e image and @e selImage parameters are an index within + the normal image list specifying the image to use for unselected and + selected items, respectively. + If @e image -1 and @e selImage is -1, the same image is used for + both selected and unselected items. + */ + wxTreeItemId PrependItem(const wxTreeItemId& parent, + const wxString& text, + int image = -1, + int selImage = -1, + wxTreeItemData* data = @NULL); + + /** + Scrolls the specified item into view. + */ + void ScrollTo(const wxTreeItemId& item); + + /** + Selects the given item. In multiple selection controls, can be also used to + deselect a currently selected item if the value of @e select is @false. + */ + void SelectItem(const wxTreeItemId& item, bool select = @true); + + /** + Sets the buttons image list (from which application-defined button images are + taken). + The button images assigned with this method will + @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. + + Setting or assigning the button image list enables the display of image buttons. + Once enabled, the only way to disable the display of button images is to set + the button image list to @NULL. + + This function is only available in the generic version. + + See also AssignButtonsImageList(). + */ + void SetButtonsImageList(wxImageList* imageList); + + /** + Sets the normal image list. Image list assigned with this method will + @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. + + See also AssignImageList(). + */ + void SetImageList(wxImageList* imageList); + + /** + Sets the indentation for the tree control. + */ + void SetIndent(int indent); + + /** + Sets the colour of the item's background. + */ + void SetItemBackgroundColour(const wxTreeItemId& item, + const wxColour& col); + + /** + Makes item appear in bold font if @e bold parameter is @true or resets it to + the normal state. + + See also: IsBold() + */ + void SetItemBold(const wxTreeItemId& item, bool bold = @true); + + //@{ + /** + Gives the item the visual feedback for Drag'n'Drop actions, which is + useful if something is dragged from the outside onto the tree control + (as opposed to a DnD operation within the tree control, which already + is implemented internally). + */ + void SetItemData(const wxTreeItemId& item, wxTreeItemData* data); + wxPython note: SetPyData(item, obj) + + + + +Associate the given Python +Object with the wxTreeItemData for the given item Id. + + + + + + + +void SetItemDropHighlight(const wxTreeItemId& item, + bool highlight = @true); + //@} + + /** + Sets the item's font. All items in the tree should have the same height to avoid + text clipping, so the fonts height should be the same for all of them, + although font attributes may vary. + + @sa SetItemBold() + */ + void SetItemFont(const wxTreeItemId& item, const wxFont& font); + + /** + Force appearance of the button next to the item. This is useful to + allow the user to expand the items which don't have any children now, + but instead adding them only when needed, thus minimizing memory + usage and loading time. + */ + void SetItemHasChildren(const wxTreeItemId& item, + bool hasChildren = @true); + + /** + Sets the specified item image. See GetItemImage() + for the description of the @e which parameter. + */ + void SetItemImage(const wxTreeItemId& item, int image, + wxTreeItemIcon which = wxTreeItemIcon_Normal); + + /** + Sets the selected item image (this function is obsolete, use + @c SetItemImage(item, wxTreeItemIcon_Selected) instead). + */ + void SetItemSelectedImage(const wxTreeItemId& item, int selImage); + + /** + Sets the item label. + */ + void SetItemText(const wxTreeItemId& item, const wxString& text); + + /** + Sets the colour of the item's text. + */ + void SetItemTextColour(const wxTreeItemId& item, + const wxColour& col); + + /** + If @true is passed, specifies that the control will use a quick calculation for + the best size, + looking only at the first and last items. Otherwise, it will look at all items. + The default is @false. + + @sa GetQuickBestSize() + */ + void SetQuickBestSize(bool quickBestSize); + + /** + Sets the state image list (from which application-defined state images are + taken). + Image list assigned with this method will + @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. + + See also AssignStateImageList(). + */ + void SetStateImageList(wxImageList* imageList); + + /** + Sets the mode flags associated with the display of the tree control. + The new mode takes effect immediately. + (Generic only; MSW ignores changes.) + */ + void SetWindowStyle(long styles); + + /** + Sorts the children of the given item using + OnCompareItems() method of wxTreeCtrl. You + should override that method to change the sort order (the default is ascending + case-sensitive alphabetical order). + + @sa wxTreeItemData, OnCompareItems() + */ + void SortChildren(const wxTreeItemId& item); + + /** + Toggles the given item between collapsed and expanded states. + */ + void Toggle(const wxTreeItemId& item); + + /** + Toggles the given item between selected and unselected states. For + multiselection controls only. + */ + void ToggleItemSelection(const wxTreeItemId& item); + + /** + Removes the selection from the currently selected item (if any). + */ + void Unselect(); + + /** + This function either behaves the same as Unselect() + if the control doesn't have wxTR_MULTIPLE style, or removes the selection from + all items if it does have this style. + */ + void UnselectAll(); + + /** + Unselects the given item. This works in multiselection controls only. + */ + void UnselectItem(const wxTreeItemId& item); +}; + + +/** + @class wxTreeEvent + @wxheader{treectrl.h} + + A tree event holds information about events associated with wxTreeCtrl objects. + + @library{wxbase} + @category{events} + + @seealso + wxTreeCtrl +*/ +class wxTreeEvent : public wxNotifyEvent +{ +public: + /** + ) + + Constructor, used by wxWidgets itself only. + */ + wxTreeEvent(wxEventType commandType, wxTreeCtrl * tree); + + /** + Returns the item (valid for all events). + */ + wxTreeItemId GetItem(); + + /** + Returns the key code if the event is a key event. Use + GetKeyEvent() to get the values of the + modifier keys for this event (i.e. Shift or Ctrl). + */ + int GetKeyCode(); + + /** + Returns the key event for @c EVT_TREE_KEY_DOWN events. + */ + const wxKeyEvent GetKeyEvent(); + + /** + Returns the label if the event is a begin or end edit label event. + */ + const wxString GetLabel(); + + /** + Returns the old item index (valid for EVT_TREE_ITEM_CHANGING and CHANGED events) + */ + wxTreeItemId GetOldItem(); + + /** + Returns the position of the mouse pointer if the event is a drag or + menu-context event. + In both cases the position is in client coordinates - i.e. relative to the + wxTreeCtrl + window (so that you can pass it directly to e.g. wxWindow::PopupMenu). + */ + wxPoint GetPoint(); + + /** + Returns @true if the label edit was cancelled. This should be + called from within an EVT_TREE_END_LABEL_EDIT handler. + */ + bool IsEditCancelled(); + + /** + Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP events). + Windows only. + */ + void SetToolTip(const wxString& tooltip); +}; diff --git a/interface/txtstrm.h b/interface/txtstrm.h new file mode 100644 index 0000000000..e2aa848797 --- /dev/null +++ b/interface/txtstrm.h @@ -0,0 +1,270 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: txtstrm.h +// Purpose: documentation for wxTextInputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextInputStream + @wxheader{txtstrm.h} + + This class provides functions that read text datas using an input stream. + So, you can read @e text floats, integers. + + The wxTextInputStream correctly reads text files (or streams) in DOS, Macintosh + and Unix formats and reports a single newline char as a line ending. + + Operator is overloaded and you can use this class like a standard C++ iostream. + Note, however, that the arguments are the fixed size types wxUint32, wxInt32 etc + and on a typical 32-bit computer, none of these match to the "long" type + (wxInt32 + is defined as int on 32-bit architectures) so that you cannot use long. To avoid + problems (here and elsewhere), make use of wxInt32, wxUint32 and similar types. + + If you're scanning through a file using wxTextInputStream, you should check for + EOF @b before + reading the next item (word / number), because otherwise the last item may get + lost. + You should however be prepared to receive an empty item (empty string / zero + number) at the + end of file, especially on Windows systems. This is unavoidable because most + (but not all) files end + with whitespace (i.e. usually a newline). + + For example: + + @code + wxFileInputStream input( "mytext.txt" ); + wxTextInputStream text( input ); + wxUint8 i1; + float f2; + wxString line; + + text i1; // read a 8 bit integer. + text i1 f2; // read a 8 bit integer followed by float. + text line; // read a text line + @endcode + + @library{wxbase} + @category{streams} + + @seealso + wxTextInputStream::SetStringSeparators +*/ +class wxTextInputStream +{ +public: + /** + ) + + Constructs a text stream associated to the given input stream. + + @param stream + The underlying input stream. + + @param sep + The initial string separator characters. + + @param conv + In Unicode build only: The encoding converter used to convert the bytes in the + underlying input stream to characters. + */ + wxTextInputStream(wxInputStream& stream, + const wxString& sep=" \t"); + + /** + Destroys the wxTextInputStream object. + */ + ~wxTextInputStream(); + + /** + Reads a character, returns 0 if there are no more characters in the stream. + */ + wxChar GetChar(); + + /** + Reads a unsigned 16 bit integer from the stream. + + See wxTextInputStream::Read8 for the + description of the @e base parameter. + */ + wxUint16 Read16(int base = 10); + + /** + Reads a signed 16 bit integer from the stream. + + See wxTextInputStream::Read8 for the + description of the @e base parameter. + */ + wxInt16 Read16S(int base = 10); + + /** + Reads a 32 bit unsigned integer from the stream. + + See wxTextInputStream::Read8 for the + description of the @e base parameter. + */ + wxUint32 Read32(int base = 10); + + /** + Reads a 32 bit signed integer from the stream. + + See wxTextInputStream::Read8 for the + description of the @e base parameter. + */ + wxInt32 Read32S(int base = 10); + + /** + Reads a single unsigned byte from the stream, given in base @e base. + + The value of @e base must be comprised between 2 and 36, inclusive, or + be a special value 0 which means that the usual rules of @c C numbers are + applied: if the number starts with @c 0x it is considered to be in base + 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note + that you may not want to specify the base 0 if you are parsing the numbers + which may have leading zeroes as they can yield unexpected (to the user not + familiar with C) results. + */ + wxUint8 Read8(int base = 10); + + /** + Reads a single signed byte from the stream. + + See wxTextInputStream::Read8 for the + description of the @e base parameter. + */ + wxInt8 Read8S(int base = 10); + + /** + Reads a double (IEEE encoded) from the stream. + */ + double ReadDouble(); + + /** + Reads a line from the input stream and returns it (without the end of line + character). + */ + wxString ReadLine(); + + /** + @b NB: This method is deprecated, use ReadLine() + or ReadWord() instead. + + Same as ReadLine(). + */ + wxString ReadString(); + + /** + Reads a word (a sequence of characters until the next separator) from the + input stream. + + @sa SetStringSeparators() + */ + wxString ReadWord(); + + /** + Sets the characters which are used to define the word boundaries in + ReadWord(). + + The default separators are the space and @c TAB characters. + */ + void SetStringSeparators(const wxString& sep); +}; + + +/** + @class wxTextOutputStream + @wxheader{txtstrm.h} + + This class provides functions that write text datas using an output stream. + So, you can write @e text floats, integers. + + You can also simulate the C++ cout class: + + @code + wxFFileOutputStream output( stderr ); + wxTextOutputStream cout( output ); + + cout "This is a text line" endl; + cout 1234; + cout 1.23456; + @endcode + + The wxTextOutputStream writes text files (or streams) on DOS, Macintosh + and Unix in their native formats (concerning the line ending). + + @library{wxbase} + @category{streams} +*/ +class wxTextOutputStream +{ +public: + /** + ) + + Constructs a text stream object associated to the given output stream. + + @param stream + The output stream. + + @param mode + The end-of-line mode. One of wxEOL_NATIVE, wxEOL_DOS, wxEOL_MAC and wxEOL_UNIX. + + @param conv + In Unicode build only: The object used to convert + Unicode text into ASCII characters written to the output stream. + */ + wxTextOutputStream(wxOutputStream& stream, + wxEOL mode = wxEOL_NATIVE); + + /** + Destroys the wxTextOutputStream object. + */ + ~wxTextOutputStream(); + + /** + Returns the end-of-line mode. One of @b wxEOL_DOS, @b wxEOL_MAC and @b + wxEOL_UNIX. + */ + wxEOL GetMode(); + + /** + Writes a character to the stream. + */ + void PutChar(wxChar c); + + /** + Set the end-of-line mode. One of @b wxEOL_NATIVE, @b wxEOL_DOS, @b wxEOL_MAC + and @b wxEOL_UNIX. + */ + void SetMode(wxEOL mode = wxEOL_NATIVE); + + /** + Writes the 16 bit integer @e i16 to the stream. + */ + void Write16(wxUint16 i16); + + /** + Writes the 32 bit integer @e i32 to the stream. + */ + void Write32(wxUint32 i32); + + /** + Writes the single byte @e i8 to the stream. + */ + void Write8(wxUint8 i8); + + /** + Writes the double @e f to the stream using the IEEE format. + */ + virtual void WriteDouble(double f); + + /** + Writes @e string as a line. Depending on the end-of-line mode the end of + line ('\n') characters in the string are converted to the correct + line ending terminator. + */ + virtual void WriteString(const wxString& string); +}; diff --git a/interface/uri.h b/interface/uri.h new file mode 100644 index 0000000000..cbb3b8e6b5 --- /dev/null +++ b/interface/uri.h @@ -0,0 +1,348 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: uri.h +// Purpose: documentation for wxURI class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxURI + @wxheader{uri.h} + + wxURI is used to extract information from + a URI (Uniform Resource Identifier). + + For information about URIs, see + RFC 3986. + + In short, a URL is a URI. In other + words, URL is a subset of a URI - all + acceptable URLs are also acceptable URIs. + + wxURI automatically escapes invalid characters in a string, + so there is no chance of wxURI "failing" on construction/creation. + + wxURI supports copy construction and standard assignment + operators. wxURI can also be inherited from to provide + furthur functionality. + + @library{wxbase} + @category{data} + + @seealso + wxURL +*/ +class wxURI : public wxObject +{ +public: + //@{ + /** + Copies this URI from another URI. + + @param uri + URI (Uniform Resource Identifier) to initialize with + */ + wxURI(); + wxURI(const wxChar* uri); + wxURI(const wxURI& uri); + //@} + + /** + Builds the URI from its individual components and adds proper separators. + + If the URI is not a reference or is not resolved, + the URI that is returned from Get is the same one + passed to Create. + */ + wxString BuildURI(); + + /** + Builds the URI from its individual components, adds proper separators, and + returns escape sequences to normal characters. + + Note that it is preferred to call this over Unescape(BuildURI()) since + BuildUnescapedURI() performs some optimizations over the plain method. + */ + wxString BuildUnescapedURI(); + + /** + Creates this URI from the string + + @param uri. + + Returns the position at which parsing stopped (there + is no such thing as an "invalid" wxURI). + + uri + string to initialize from + */ + const wxChar* Create(const wxString uri); + + /** + Note that on URIs with a "file" scheme wxURI does not + parse the userinfo, server, or port portion. This is to keep + compatability with wxFileSystem, the old wxURL, and older url specifications. + */ + + + /** + Obtains the fragment of this URI. + + The fragment of a URI is the last value of the URI, + and is the value after a '' character after the path + of the URI. + + @c http://mysite.com/mypath#fragment + */ + const wxString GetFragment(); + + /** + Obtains the host type of this URI, which is of type + HostType(): + + + @b wxURI_REGNAME + + + Server is a host name, or the Server component itself is undefined. + + @b wxURI_IPV4ADDRESS + + + Server is a IP version 4 address (XXX.XXX.XXX.XXX) + + @b wxURI_IPV6ADDRESS + + + Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX + + @b wxURI_IPVFUTURE + + + Server is an IP address, but not versions 4 or 6 + */ + const HostType GetHostType(); + + /** + Returns the password part of the userinfo component of + this URI. Note that this is explicitly depreciated by + RFC 1396 and should generally be avoided if possible. + + @c http://user:password@mysite.com/mypath + */ + const wxString GetPassword(); + + /** + Returns the (normalized) path of the URI. + + The path component of a URI comes + directly after the scheme component + if followed by zero or one slashes ('/'), + or after the server/port component. + + Absolute paths include the leading '/' + character. + + @c http://mysite.compath + */ + const wxString GetPath(); + + /** + Returns a string representation of the URI's port. + + The Port of a URI is a value after the server, and + must come after a colon (:). + + @c http://mysite.com:port + + Note that you can easily get the numeric value of the port + by using wxAtoi or wxString::Format. + */ + const wxString GetPort(); + + /** + Returns the Query component of the URI. + + The query component is what is commonly passed to a + cgi application, and must come after the path component, + and after a '?' character. + + @c http://mysite.com/mypath?query + */ + const wxString GetQuery(); + + /** + Returns the Scheme component of the URI. + + The first part of the uri. + + @c scheme://mysite.com + */ + const wxString GetScheme(); + + /** + Returns the Server component of the URI. + + The server of the uri can be a server name or + a type of ip address. See + GetHostType() for the + possible values for the host type of the + server component. + + @c http://server/mypath + */ + const wxString GetServer(); + + /** + Returns the username part of the userinfo component of + this URI. Note that this is explicitly depreciated by + RFC 1396 and should generally be avoided if possible. + + @c http://user:password@mysite.com/mypath + */ + const wxString GetUser(); + + /** + Returns the UserInfo component of the URI. + + The component of a URI before the server component + that is postfixed by a '@' character. + + @c http://userinfo@mysite.com/mypath + */ + const wxString GetUserInfo(); + + /** + Returns @true if the Fragment component of the URI exists. + */ + bool HasFragment(); + + /** + Returns @true if the Path component of the URI exists. + */ + bool HasPath(); + + /** + Returns @true if the Port component of the URI exists. + */ + bool HasPort(); + + /** + Returns @true if the Query component of the URI exists. + */ + bool HasQuery(); + + /** + Returns @true if the Scheme component of the URI exists. + */ + bool HasScheme(); + + /** + Returns @true if the Server component of the URI exists. + */ + bool HasServer(); + + /** + Returns @true if the User component of the URI exists. + */ + bool HasUser(); + + /** + Returns @true if a valid [absolute] URI, otherwise this URI + is a URI reference and not a full URI, and IsReference + returns @false. + */ + bool IsReference(); + + /** + To obtain individual components you can use + one of the following methods + + GetScheme() + + GetUserInfo() + + GetServer() + + GetPort() + + GetPath() + + GetQuery() + + GetFragment() + + However, you should check HasXXX before + calling a get method, which determines whether or not the component referred + to by the method is defined according to RFC 2396. + + Consider an undefined component equivalent to a + @NULL C string. + + + HasScheme() + + HasUserInfo() + + HasServer() + + @ref hasserver() HasPort + + HasPath() + + HasQuery() + + HasFragment() + + Example: + */ + + + /** + Inherits this URI from a base URI - components that do not + exist in this URI are copied from the base, and if this URI's + path is not an absolute path (prefixed by a '/'), then this URI's + path is merged with the base's path. + + For instance, resolving "../mydir" from "http://mysite.com/john/doe" + results in the scheme (http) and server (mysite.com) being copied into + this URI, since they do not exist. In addition, since the path + of this URI is not absolute (does not begin with '/'), the path + of the base's is merged with this URI's path, resulting in the URI + "http://mysite.com/john/mydir". + + @param base + Base URI to inherit from. Must be a full URI and not a reference + + @param flags + Currently either wxURI_STRICT or 0, in non-strict + mode some compatibility layers are enabled to allow loopholes from RFCs prior + to 2396 + */ + void Resolve(const wxURI& base, int flags = wxURI_STRICT); + + /** + Translates all escape sequences (normal characters and returns the result. + + This is the preferred over deprecated wxURL::ConvertFromURI. + + If you want to unescape an entire wxURI, use BuildUnescapedURI() instead, + as it performs some optimizations over this method. + + @param uri + string with escaped characters to convert + */ + wxString Unescape(const wxString& uri); + + /** + Compares this URI to another URI, and returns @true if + this URI equals + + @param uricomp, otherwise it returns @false. + + uricomp + URI to compare to + */ + void operator ==(const wxURI& uricomp); +}; diff --git a/interface/url.h b/interface/url.h new file mode 100644 index 0000000000..ff1ed7915d --- /dev/null +++ b/interface/url.h @@ -0,0 +1,143 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: url.h +// Purpose: documentation for wxURL class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxURL + @wxheader{url.h} + + wxURL is a specialization of wxURI for parsing URLs. + Please look at wxURI documentation for more info about the functions + you can use to retrieve the various parts of the URL (scheme, server, port, + etc). + + Supports standard assignment operators, copy constructors, + and comparison operators. + + @library{wxnet} + @category{net} + + @seealso + wxSocketBase, wxProtocol +*/ +class wxURL : public wxURI +{ +public: + /** + Constructs a URL object from the string. The URL must be valid according + to RFC 1738. In particular, file URLs must be of the format + @c file://hostname/path/to/file otherwise GetError() + will return a value different from @c wxURL_NOERR. + + It is valid to leave out the hostname but slashes must remain in place - + i.e. a file URL without a hostname must contain three consecutive slashes + (e.g. @c file:///somepath/myfile). + + @param url + Url string to parse. + */ +#define wxURL(const wxString& url = wxEmptyString) /* implementation is private */ + + /** + Destroys the URL object. + */ +#define ~wxURL() /* implementation is private */ + + /** + Returns the last error. This error refers to the URL parsing or to the protocol. + It can be one of these errors: + + + @b wxURL_NOERR + + + No error. + + @b wxURL_SNTXERR + + + Syntax error in the URL string. + + @b wxURL_NOPROTO + + + Found no protocol which can get this URL. + + @b wxURL_NOHOST + + + A host name is required for this protocol. + + @b wxURL_NOPATH + + + A path is required for this protocol. + + @b wxURL_CONNERR + + + Connection error. + + @b wxURL_PROTOERR + + + An error occurred during negotiation. + */ + wxURLError GetError(); + + /** + Creates a new input stream on the specified URL. You can use all but seek + functionality of wxStream. Seek isn't available on all streams. For example, + HTTP or FTP streams don't deal with it. + + Note that this method is somewhat deprecated, all future wxWidgets applications + should really use wxFileSystem instead. + + Example: + + @returns Returns the initialized stream. You will have to delete it + yourself. + + @sa wxInputStream + */ + wxInputStream * GetInputStream(); + + /** + Returns a reference to the protocol which will be used to get the URL. + */ + wxProtocol GetProtocol(); + + /** + Returns @true if this object is correctly initialized, i.e. if + GetError() returns @c wxURL_NOERR. + */ +#define bool IsOk() /* implementation is private */ + + /** + Sets the default proxy server to use to get the URL. The string specifies + the proxy like this: hostname:port number. + + @param url_proxy + Specifies the proxy to use + + @sa SetProxy() + */ + static void SetDefaultProxy(const wxString& url_proxy); + + /** + Sets the proxy to use for this URL. + + @sa SetDefaultProxy() + */ + void SetProxy(const wxString& url_proxy); + + /** + Initializes this object with the given URL and returns @c wxURL_NOERR + if it's valid (see GetError() for more info). + */ +#define wxURLError SetURL(const wxString& url) /* implementation is private */ +}; diff --git a/interface/utils.h b/interface/utils.h new file mode 100644 index 0000000000..c071d6b66f --- /dev/null +++ b/interface/utils.h @@ -0,0 +1,712 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: utils.h +// Purpose: documentation for wxWindowDisabler class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWindowDisabler + @wxheader{utils.h} + + This class disables all windows of the application (may be with the exception + of one of them) in its constructor and enables them back in its destructor. + This comes in handy when you want to indicate to the user that the application + is currently busy and cannot respond to user input. + + @library{wxcore} + @category{FIXME} + + @seealso + wxBusyCursor +*/ +class wxWindowDisabler +{ +public: + /** + Disables all top level windows of the applications with the exception of + @e winToSkip if it is not @NULL. + */ + wxWindowDisabler(wxWindow * winToSkip = @NULL); + + /** + Reenables back the windows disabled by the constructor. + */ + ~wxWindowDisabler(); +}; + + +/** + @class wxBusyCursor + @wxheader{utils.h} + + This class makes it easy to tell your user that the program is temporarily busy. + Just create a wxBusyCursor object on the stack, and within the current scope, + the hourglass will be shown. + + For example: + + @code + wxBusyCursor wait; + + for (int i = 0; i 100000; i++) + DoACalculation(); + @endcode + + It works by calling wxBeginBusyCursor in the constructor, + and wxEndBusyCursor in the destructor. + + @library{wxcore} + @category{FIXME} + + @seealso + wxBeginBusyCursor, wxEndBusyCursor, wxWindowDisabler +*/ +class wxBusyCursor +{ +public: + /** + Constructs a busy cursor object, calling wxBeginBusyCursor. + */ + wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); + + /** + Destroys the busy cursor object, calling wxEndBusyCursor. + */ + ~wxBusyCursor(); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Returns the type of power source as one of @c wxPOWER_SOCKET, + @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. + @c wxPOWER_UNKNOWN is also the default on platforms where this + feature is not implemented (currently everywhere but MS Windows). +*/ +wxPowerType wxGetPowerType(); + +//@{ +/** + This function returns the "user id" also known as "login name" under Unix i.e. + something like "jsmith". It uniquely identifies the current user (on this + system). + + Under Windows or NT, this function first looks in the environment + variables USER and LOGNAME; if neither of these is found, the entry @b UserId + in the @b wxWidgets section of the WIN.INI file is tried. + + The first variant of this function returns the login name if successful or an + empty string otherwise. The second (deprecated) function returns @true + if successful, @false otherwise. + + @sa wxGetUserName +*/ +wxString wxGetUserId(); + bool wxGetUserId(char * buf, int sz); +//@} + +/** + @b NB: This function is now obsolete, please use + wxLogFatalError instead. + + Displays @e msg and exits. This writes to standard error under Unix, + and pops up a message box under Windows. Used for fatal internal + wxWidgets errors. See also wxError. +*/ +void wxFatalError(const wxString& msg, + const wxString& title = "wxWidgets Fatal Error"); + +/** + Returns battery state as one of @c wxBATTERY_NORMAL_STATE, + @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE, + @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE. + @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where + this feature is not implemented (currently everywhere but MS Windows). +*/ +wxBatteryState wxGetBatteryState(); + +/** + @b NB: This function is obsolete, please use + wxWindow::FindWindowByName instead. + + Find a window by its name (as given in a window constructor or @b Create + function call). + If @e parent is @NULL, the search will start from all top-level + frames and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + + If no such named window is found, @b wxFindWindowByLabel is called. +*/ +wxWindow * wxFindWindowByName(const wxString& name, + wxWindow * parent=@NULL); + +/** + Changes the cursor back to the original cursor, for all windows in the + application. + Use with wxBeginBusyCursor. + + See also wxIsBusy, wxBusyCursor. +*/ +void wxEndBusyCursor(); + +/** + This function is deprecated as the ids generated by it can conflict with the + ids defined by the user code, use @c wxID_ANY to assign ids which are + guaranteed to not conflict with the user-defined ids for the controls and menu + items you create instead of using this function. + Generates an integer identifier unique to this run of the program. +*/ +long wxNewId(); + +/** + Ensures that ids subsequently generated by @b NewId do not clash with + the given @b id. +*/ +void wxRegisterId(long id); + +/** + @b NB: This function is now obsolete, replaced by Log + functions and wxLogDebug in particular. + + Display a debugging message; under Windows, this will appear on the + debugger command window, and under Unix, it will be written to standard + error. + + The syntax is identical to @b printf: pass a format string and a + variable list of arguments. + + @b Tip: under Windows, if your application crashes before the + message appears in the debugging window, put a wxYield call after + each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s + (at least for Watcom C++): preformat your messages and use OutputDebugString + instead. +*/ +void wxDebugMsg(const wxString& fmt, ... ); + +/** + For normal keys, returns @true if the specified key is currently down. + + For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns + @true if the key is toggled such that its LED indicator is lit. There is + currently no way to test whether togglable keys are up or down. + + Even though there are virtual key codes defined for mouse buttons, they + cannot be used with this function currently. +*/ +bool wxGetKeyState(wxKeyCode key); + +/** + Returns the string containing the description of the current platform in a + user-readable form. For example, this function may return strings like + @c Windows NT Version 4.0 or @c Linux 2.2.2 i386. + + @sa ::wxGetOsVersion +*/ +wxString wxGetOsDescription(); + +/** + Return the (current) user's home directory. + + @sa wxGetUserHome, wxStandardPaths +*/ +wxString wxGetHomeDir(); + +/** + Sleeps for the specified number of milliseconds. Notice that usage of this + function is encouraged instead of calling usleep(3) directly because the + standard usleep() function is not MT safe. +*/ +void wxMilliSleep(unsigned long milliseconds); + +/** + Sleeps for the specified number of microseconds. The microsecond resolution may + not, in fact, be available on all platforms (currently only Unix platforms with + nanosleep(2) may provide it) in which case this is the same as + wxMilliSleep(@e microseconds/1000). +*/ +void wxMicroSleep(unsigned long microseconds); + +/** + Shows a message box with the information about the wxWidgets build used, + including its version, most important build parameters and the version of the + underlying GUI toolkit. This is mainly used for diagnostic purposes and can be + invoked by Ctrl-Alt-middle clicking on any wxWindow which doesn't otherwise + handle this event. + + This function is new since wxWidgets version 2.9.0 +*/ +void wxInfoMessageBox(wxWindow ( parent = @NULL); + +/** + Find a menu item identifier associated with the given frame's menu bar. +*/ +int wxFindMenuItemId(wxFrame * frame, const wxString& menuString, + const wxString& itemString); + +/** + This function enables or disables all top level windows. It is used by + ::wxSafeYield. +*/ +void wxEnableTopLevelWindows(bool enable = @true); + +/** + Strips any menu codes from @e str and returns the result. + + By default, the functions strips both the mnemonics character (@c '') + which is used to indicate a keyboard shortkey, and the accelerators, which are + used only in the menu items and are separated from the main text by the + @c \t (TAB) character. By using @e flags of + @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former + or the latter part, respectively. + + Notice that in most cases + wxMenuItem::GetLabelFromText or + wxControl::GetLabelText can be used instead. +*/ +wxString wxStripMenuCodes(const wxString& str, + int flags = wxStrip_All); + +/** + @b NB: This function is now obsolete, please use wxLogError + instead. + + Displays @e msg and continues. This writes to standard error under + Unix, and pops up a message box under Windows. Used for internal + wxWidgets errors. See also wxFatalError. +*/ +void wxError(const wxString& msg, + const wxString& title = "wxWidgets Internal Error"); + +/** + Open the @e url in user's default browser. If @e flags parameter contains + @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL + (currently this is only supported under Windows). The @e url may also be a + local file path (with or without @c file:// prefix), if it doesn't + correspond to an existing file and the URL has no scheme @c http:// is + prepended to it by default. + + Returns @true if the application was successfully launched. + + Note that for some configurations of the running user, the application which + is launched to open the given URL may be URL-dependent (e.g. a browser may be + used for + local URLs while another one may be used for remote URLs). +*/ +bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); + +/** + Executes a command in an interactive shell window. If no command is + specified, then just the shell is spawned. + + See also wxExecute, @ref overview_sampleexec "Exec sample". +*/ +bool wxShell(const wxString& command = @NULL); + +/** + Gets the version and the operating system ID for currently running OS. + See wxPlatformInfo for more details about wxOperatingSystemId. + + @sa ::wxGetOsDescription, wxPlatformInfo +*/ +wxOperatingSystemId wxGetOsVersion(int * major = @NULL, + int * minor = @NULL); + +/** + Returns the FQDN (fully qualified domain host name) or an empty string on + error. + + @sa wxGetHostName +*/ +wxString wxGetFullHostName(); + +/** + Changes the cursor to the given cursor for all windows in the application. + Use wxEndBusyCursor to revert the cursor back + to its previous state. These two calls can be nested, and a counter + ensures that only the outer calls take effect. + + See also wxIsBusy, wxBusyCursor. +*/ +void wxBeginBusyCursor(wxCursor * cursor = wxHOURGLASS_CURSOR); + +/** + Tells the system to delete the specified object when + all other events have been processed. In some environments, it is + necessary to use this instead of deleting a frame directly with the + delete operator, because some GUIs will still send events to a deleted window. + + Now obsolete: use wxWindow::Close instead. +*/ +void wxPostDelete(wxObject * object); + +/** + @b NB: This function is obsolete, please use + wxWindow::FindWindowByLabel instead. + + Find a window by its label. Depending on the type of window, the label may be a + window title + or panel item label. If @e parent is @NULL, the search will start from all + top-level + frames and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. +*/ +wxWindow * wxFindWindowByLabel(const wxString& label, + wxWindow * parent=@NULL); + +/** + This function is similar to wxYield, except that it disables the user input to + all program windows before calling wxYield and re-enables it again + afterwards. If @e win is not @NULL, this window will remain enabled, + allowing the implementation of some limited user interaction. + + Returns the result of the call to ::wxYield. +*/ +bool wxSafeYield(wxWindow* win = @NULL, bool onlyIfNeeded = @false); + +/** + Returns the mouse position in screen coordinates. +*/ +wxPoint wxGetMousePosition(); + +/** + Loads a user-defined Windows resource as a string. If the resource is found, + the function creates + a new character array and copies the data into it. A pointer to this data is + returned. If unsuccessful, @NULL is returned. + + The resource must be defined in the @c .rc file using the following syntax: + @code + myResource TEXT file.ext + @endcode + + where @c file.ext is a file that the resource compiler can find. + + This function is available under Windows only. +*/ +wxString wxLoadUserResource(const wxString& resourceName, + const wxString& resourceType="TEXT"); + +/** + Returns the amount of free memory in bytes under environments which + support it, and -1 if not supported or failed to perform measurement. +*/ +wxMemorySize wxGetFreeMemory(); + +/** + This is a macro defined as @c getenv() or its wide char version in Unicode + mode. + + Note that under Win32 it may not return correct value for the variables set + with wxSetEnv, use wxGetEnv function + instead. +*/ +wxChar * wxGetEnv(const wxString& var); + +//@{ +/** + Copies the current host machine's name into the supplied buffer. Please note + that the returned name is @e not fully qualified, i.e. it does not include + the domain name. + + Under Windows or NT, this function first looks in the environment + variable SYSTEM_NAME; if this is not found, the entry @b HostName + in the @b wxWidgets section of the WIN.INI file is tried. + + The first variant of this function returns the hostname if successful or an + empty string otherwise. The second (deprecated) function returns @true + if successful, @false otherwise. + + @sa wxGetFullHostName +*/ +wxString wxGetHostName(); + bool wxGetHostName(char * buf, int sz); +//@} + +/** + Returns the current value of the environment variable @e var in @e value. + @e value may be @NULL if you just want to know if the variable exists + and are not interested in its value. + + Returns @true if the variable exists, @false otherwise. +*/ +bool wxGetEnv(const wxString& var, wxString * value); + +/** + Under X only, returns the current display name. See also wxSetDisplayName. +*/ +wxString wxGetDisplayName(); + +/** + Ring the system bell. + + Note that this function is categorized as a GUI one and so is not thread-safe. +*/ +void wxBell(); + +/** + Returns the home directory for the given user. If the @e user is empty + (default value), this function behaves like + wxGetHomeDir i.e. returns the current user home + directory. + + If the home directory couldn't be determined, an empty string is returned. +*/ +wxString wxGetUserHome(const wxString& user = ""); + +//@{ +/** + @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr + and it only takes the @c command argument, + and returns a 3-element list @c ( status, output, errors ), where + @c output and @c errors are array references. + + Executes another program in Unix or Windows. + + The first form takes a command string, such as @c "emacs file.txt". + + The second form takes an array of values: a command, any number of + arguments, terminated by @NULL. + + The semantics of the third and fourth versions is different from the first two + and is described in more details below. + + If @e flags parameter contains @c wxEXEC_ASYNC flag (the default), flow + of control immediately returns. If it contains @c wxEXEC_SYNC, the current + application waits until the other program has terminated. + + In the case of synchronous execution, the return value is the exit code of + the process (which terminates by the moment the function returns) and will be + -1 if the process couldn't be started and typically 0 if the process + terminated successfully. Also, while waiting for the process to + terminate, wxExecute will call wxYield. Because of this, by + default this function disables all application windows to avoid unexpected + reentrancies which could result from the users interaction with the program + while the child process is running. If you are sure that it is safe to not + disable the program windows, you may pass @c wxEXEC_NODISABLE flag to + prevent this automatic disabling from happening. + + For asynchronous execution, however, the return value is the process id and + zero value indicates that the command could not be executed. As an added + complication, the return value of -1 in this case indicates that we didn't + launch a new process, but connected to the running one (this can only happen in + case of using DDE under Windows for command execution). In particular, in this, + and only this, case the calling code will not get the notification about + process termination. + + If callback isn't @NULL and if execution is asynchronous, + wxProcess::OnTerminate will be called when + the process finishes. Specifying this parameter also allows you to redirect the + standard input and/or output of the process being launched by calling + wxProcess::Redirect. If the child process IO is redirected, + under Windows the process window is not shown by default (this avoids having to + flush an unnecessary console for the processes which don't create any windows + anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from + happening, i.e. with this flag the child process window will be shown normally. + + Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure + that the new process is a group leader (this will create a new session if + needed). Calling wxKill passing wxKILL_CHILDREN will + kill this process as well as all of its children (except those which have + started their own session). + + The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking + place while the child process is running. It should be only used for very + short-lived processes as otherwise the application windows risk becoming + unresponsive from the users point of view. As this flag only makes sense with + @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags + is provided as a convenience. + + Finally, you may use the third overloaded version of this function to execute + a process (always synchronously, the contents of @e flags is or'd with + @c wxEXEC_SYNC) and capture its output in the array @e output. The + fourth version adds the possibility to additionally capture the messages from + standard error output in the @e errors array. + + @b NB: Currently wxExecute() can only be used from the main thread, calling + this function from another thread will result in an assert failure in debug + build and won't work. + + @param command + The command to execute and any parameters to pass to it as a + single string. + + @param argv + The command to execute should be the first element of this + array, any additional ones are the command parameters and the array must be + terminated with a @NULL pointer. + + @param flags + Combination of bit masks wxEXEC_ASYNC, + wxEXEC_SYNC and wxEXEC_NOHIDE + + @param callback + An optional pointer to wxProcess + + @sa wxShell, wxProcess, @ref overview_sampleexec "Exec sample". +*/ +long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC, + wxProcess * callback = @NULL); + wxPerl note: long wxExecute(char ** argv, + int flags = wxEXEC_ASYNC, + wxProcess * callback = @NULL); + wxPerl note: long wxExecute(const wxString& command, + wxArrayString& output, + int flags = 0); + wxPerl note: long wxExecute(const wxString& command, + wxArrayString& output, + wxArrayString& errors, + int flags = 0); +//@} + +/** + Returns a string representing the current date and time. +*/ +wxString wxNow(); + +/** + Returns @true if the operating system the program is running under is 64 bit. + The check is performed at run-time and may differ from the value available at + compile-time (at compile-time you can just check if @c sizeof(void*)==8) + since the program could be running in emulation mode or in a mixed 32/64 bit + system + (bi-architecture operating system). + + Very important: this function is not 100% reliable on some systems given the + fact + that there isn't always a standard way to do a reliable check on the OS + architecture. +*/ +bool wxIsPlatform64Bit(); + +/** + Returns the number uniquely identifying the current process in the system. + + If an error occurs, 0 is returned. +*/ +unsigned long wxGetProcessId(); + +/** + Equivalent to the Unix kill function: send the given signal @e sig to the + process with PID @e pid. The valid signal values are + @code + enum wxSignal + { + wxSIGNONE = 0, // verify if the process exists under Unix + wxSIGHUP, + wxSIGINT, + wxSIGQUIT, + wxSIGILL, + wxSIGTRAP, + wxSIGABRT, + wxSIGEMT, + wxSIGFPE, + wxSIGKILL, // forcefully kill, dangerous! + wxSIGBUS, + wxSIGSEGV, + wxSIGSYS, + wxSIGPIPE, + wxSIGALRM, + wxSIGTERM // terminate the process gently + }; + @endcode + + @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning + under both Unix and Windows but all the other signals are equivalent to + @c wxSIGTERM under Windows. + + Returns 0 on success, -1 on failure. If @e rc parameter is not @NULL, it will + be filled with an element of @c wxKillError enum: + @code + enum wxKillError + { + wxKILL_OK, // no error + wxKILL_BAD_SIGNAL, // no such signal + wxKILL_ACCESS_DENIED, // permission denied + wxKILL_NO_PROCESS, // no such process + wxKILL_ERROR // another, unspecified error + }; + @endcode + + The @e flags parameter can be wxKILL_NOCHILDREN (the default), + or wxKILL_CHILDREN, in which case the child processes of this + process will be killed too. Note that under Unix, for wxKILL_CHILDREN + to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER + to wxExecute. + + @sa wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample" +*/ +int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = @NULL, + int flags = 0); + +/** + Returns the current state of the mouse. Returns a wxMouseState + instance that contains the current position of the mouse pointer in + screen coordinates, as well as boolean values indicating the up/down + status of the mouse buttons and the modifier keys. +*/ +wxMouseState wxGetMouseState(); + +/** + Returns @true if between two wxBeginBusyCursor and + wxEndBusyCursor calls. + + See also wxBusyCursor. +*/ +bool wxIsBusy(); + +//@{ +/** + Copies the user's email address into the supplied buffer, by + concatenating the values returned by wxGetFullHostName + and wxGetUserId. + + Returns @true if successful, @false otherwise. +*/ +wxString wxGetEmailAddress(); + bool wxGetEmailAddress(char * buf, int sz); +//@} + +/** + Sleeps for the specified number of seconds. +*/ +void wxSleep(int secs); + +/** + Sets the value of the environment variable @e var (adding it if necessary) + to @e value. + + Returns @true on success. + + @sa wxUnsetEnv +*/ +bool wxSetEnv(const wxString& var, const wxString& value); + +/** + Returns @true if the current platform is little endian (instead of big + endian). + The check is performed at run-time. + + @sa @ref overview_byteordermacros "Byte order macros" +*/ +bool wxIsPlatformLittleEndian(); + +/** + Under X only, sets the current display name. This is the X host and display + name such + as "colonsay:0.0", and the function indicates which display should be used for + creating + windows from this point on. Setting the display within an application allows + multiple + displays to be used. + + See also wxGetDisplayName. +*/ +void wxSetDisplayName(const wxString& displayName); + diff --git a/interface/valgen.h b/interface/valgen.h new file mode 100644 index 0000000000..263687d32c --- /dev/null +++ b/interface/valgen.h @@ -0,0 +1,80 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: valgen.h +// Purpose: documentation for wxGenericValidator class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGenericValidator + @wxheader{valgen.h} + + wxGenericValidator performs data transfer (but not validation or filtering) for + the following + basic controls: wxButton, wxCheckBox, wxListBox, wxStaticText, wxRadioButton, + wxRadioBox, + wxChoice, wxComboBox, wxGauge, wxSlider, wxScrollBar, wxSpinButton, wxTextCtrl, + wxCheckListBox. + + It checks the type of the window and uses an appropriate type for that window. + For example, + wxButton and wxTextCtrl transfer data to and from a wxString variable; + wxListBox uses a + wxArrayInt; wxCheckBox uses a bool. + + For more information, please see @ref overview_validatoroverview "Validator + overview". + + @library{wxcore} + @category{validator} + + @seealso + @ref overview_validatoroverview "Validator overview", wxValidator, + wxTextValidator +*/ +class wxGenericValidator : public wxValidator +{ +public: + //@{ + /** + Constructor taking a wxDateTime pointer. This will be + used for wxDatePickerCtrl. + + @param validator + Validator to copy. + + @param valPtr + A pointer to a variable that contains the value. This variable + should have a lifetime equal to or longer than the validator lifetime (which is + usually + determined by the lifetime of the window). + */ + wxGenericValidator(const wxGenericValidator& validator); + wxGenericValidator(bool* valPtr); + wxGenericValidator(wxString* valPtr); + wxGenericValidator(int* valPtr); + wxGenericValidator(wxArrayInt* valPtr); + wxGenericValidator(wxDateTime* valPtr); + //@} + + /** + Destructor. + */ + ~wxGenericValidator(); + + /** + Clones the generic validator using the copy constructor. + */ + virtual wxValidator* Clone(); + + /** + Transfers the value from the window to the appropriate data type. + */ + virtual bool TransferFromWindow(); + + /** + Transfers the value to the window. + */ + virtual bool TransferToWindow(); +}; diff --git a/interface/validate.h b/interface/validate.h new file mode 100644 index 0000000000..64402f990d --- /dev/null +++ b/interface/validate.h @@ -0,0 +1,102 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: validate.h +// Purpose: documentation for wxValidator class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxValidator + @wxheader{validate.h} + + wxValidator is the base class for a family of validator classes that mediate + between a class of control, and application data. + + A validator has three major roles: + + to transfer data from a C++ variable or own storage to and from a control; + to validate data in a control, and show an appropriate error message; + to filter events (such as keystrokes), thereby changing the behaviour of the + associated control. + + Validators can be plugged into controls dynamically. + + To specify a default, 'null' validator, use the symbol @b wxDefaultValidator. + + For more information, please see @ref overview_validatoroverview "Validator + overview". + + @b wxPython note: If you wish to create a validator class in wxPython you should + derive the class from @c wxPyValidator in order to get Python-aware + capabilities for the various virtual methods. + + @library{wxcore} + @category{validator} + + @seealso + @ref overview_validatoroverview "Validator overview", wxTextValidator, + wxGenericValidator, +*/ +class wxValidator : public wxEvtHandler +{ +public: + /** + Constructor. + */ + wxValidator(); + + /** + Destructor. + */ + ~wxValidator(); + + /** + All validator classes must implement the @b Clone function, which returns + an identical copy of itself. This is because validators are passed to control + constructors as references which must be copied. Unlike objects such as pens + and brushes, it does not make sense to have a reference counting scheme + to do this cloning, because all validators should have separate + data. + + This base function returns @NULL. + */ + virtual wxObject* Clone(); + + /** + Returns the window associated with the validator. + */ + wxWindow* GetWindow(); + + /** + This functions switches on or turns off the error sound produced by the + validators if an invalid key is pressed. + */ + void SetBellOnError(bool doIt = @true); + + /** + Associates a window with the validator. + */ + void SetWindow(wxWindow* window); + + /** + This overridable function is called when the value in the window must be + transferred to the validator. Return @false if there is a problem. + */ + virtual bool TransferToWindow(); + + /** + This overridable function is called when the value associated with the + validator must be + transferred to the window. Return @false if there is a problem. + */ + virtual bool TransferToWindow(); + + /** + This overridable function is called when the value in the associated window + must be validated. + Return @false if the value in the window is not valid; you may pop up an error + dialog. + */ + virtual bool Validate(wxWindow* parent); +}; diff --git a/interface/valtext.h b/interface/valtext.h new file mode 100644 index 0000000000..90dfd6ea8c --- /dev/null +++ b/interface/valtext.h @@ -0,0 +1,159 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: valtext.h +// Purpose: documentation for wxTextValidator class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextValidator + @wxheader{valtext.h} + + wxTextValidator validates text controls, providing a variety of filtering + behaviours. + + For more information, please see @ref overview_validatoroverview "Validator + overview". + + @library{wxcore} + @category{validator} + + @seealso + @ref overview_validatoroverview "Validator overview", wxValidator, + wxGenericValidator +*/ +class wxTextValidator : public wxValidator +{ +public: + //@{ + /** + Constructor, taking a style and optional pointer to a wxString variable. + + @param style + A bitlist of flags, which can be: + + + wxFILTER_NONE + + + No filtering takes place. + + wxFILTER_ASCII + + + Non-ASCII characters are filtered out. + + wxFILTER_ALPHA + + + Non-alpha characters are filtered out. + + wxFILTER_ALPHANUMERIC + + + Non-alphanumeric characters are filtered out. + + wxFILTER_NUMERIC + + + Non-numeric characters are filtered out. + + wxFILTER_INCLUDE_LIST + + + Use an include list. The validator + checks if the user input is on the list, complaining if not. See + SetIncludes(). + + wxFILTER_EXCLUDE_LIST + + + Use an exclude list. The validator + checks if the user input is on the list, complaining if it is. See + SetExcludes(). + + wxFILTER_INCLUDE_CHAR_LIST + + + Use an include list. The validator + checks if each input character is in the list (one character per list element), + complaining if not. + See SetIncludes(). + + wxFILTER_EXCLUDE_CHAR_LIST + + + Use an include list. The validator + checks if each input character is in the list (one character per list element), + complaining if it is. + See SetExcludes(). + + @param valPtr + A pointer to a wxString variable that contains the value. This variable + should have a lifetime equal to or longer than the validator lifetime (which is + usually + determined by the lifetime of the window). + */ + wxTextValidator(const wxTextValidator& validator); + wxTextValidator(long style = wxFILTER_NONE, + wxString* valPtr = @NULL); + //@} + + /** + Clones the text validator using the copy constructor. + */ + virtual wxValidator* Clone(); + + /** + Returns a reference to the exclude list (the list of invalid values). + */ + wxArrayString GetExcludes(); + + /** + Returns a reference to the include list (the list of valid values). + */ + wxArrayString GetIncludes(); + + /** + Returns the validator style. + */ + long GetStyle(); + + /** + Receives character input from the window and filters it according to the + current validator style. + */ + void OnChar(wxKeyEvent& event); + + /** + Sets the exclude list (invalid values for the user input). + */ + void SetExcludes(const wxArrayString& stringList); + + /** + Sets the include list (valid values for the user input). + */ + void SetIncludes(const wxArrayString& stringList); + + /** + Sets the validator style. + */ + void SetStyle(long style); + + /** + Transfers the value in the text control to the string. + */ + virtual bool TransferFromWindow(); + + /** + Transfers the string value to the text control. + */ + virtual bool TransferToWindow(); + + /** + Validates the window contents against the include or exclude lists, depending + on the validator style. + */ + virtual bool Validate(wxWindow* parent); +}; diff --git a/interface/variant.h b/interface/variant.h new file mode 100644 index 0000000000..571b36795d --- /dev/null +++ b/interface/variant.h @@ -0,0 +1,508 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: variant.h +// Purpose: documentation for wxVariant class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxVariant + @wxheader{variant.h} + + The @b wxVariant class represents a container for any type. + A variant's value can be changed at run time, possibly to a different type of + value. + + As standard, wxVariant can store values of type bool, wxChar, double, long, + string, + string list, time, date, void pointer, list of strings, and list of variants. + However, an application can extend wxVariant's capabilities by deriving from the + class wxVariantData and using the wxVariantData form of + the wxVariant constructor or assignment operator to assign this data to a + variant. + Actual values for user-defined types will need to be accessed via the + wxVariantData + object, unlike the case for basic data types where convenience functions such as + wxVariant::GetLong can be used. + + Pointers to any wxObject derived class can also easily be stored + in a wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set + the + type name (returned by wxVariant::GetType) and to perform + type-safety checks at runtime. + + This class is useful for reducing the programming for certain tasks, such as an + editor + for different data types, or a remote procedure call protocol. + + An optional name member is associated with a wxVariant. This might be used, for + example, + in CORBA or OLE automation classes, where named parameters are required. + + Note that as of wxWidgets 2.7.1, wxVariant is @ref overview_trefcount + "reference counted". + Additionally, the convenience macros @b DECLARE_VARIANT_OBJECT and + @b IMPLEMENT_VARIANT_OBJECT were added so that adding (limited) support + for conversion to and from wxVariant can be very easily implemented without + modifying + either wxVariant or the class to be stored by wxVariant. Since assignment + operators + cannot be declared outside the class, the shift left operators are used like + this: + + @code + // in the header file + DECLARE_VARIANT_OBJECT(MyClass) + + // in the implementation file + IMPLEMENT_VARIANT_OBJECT(MyClass) + + // in the user code + wxVariant variant; + MyClass value; + variant value; + + // or + value variant; + @endcode + + For this to work, MyClass must derive from wxObject, implement + the @ref overview_runtimeclassoverview "wxWidgets RTTI system" + and support the assignment operator and equality operator for itself. Ideally, + it + should also be reference counted to make copying operations cheap and fast. This + can be most easily implemented using the reference counting support offered by + wxObject itself. By default, wxWidgets already implements + the shift operator conversion for a few of its drawing related classes: + + @code + IMPLEMENT_VARIANT_OBJECT(wxColour) + IMPLEMENT_VARIANT_OBJECT(wxImage) + IMPLEMENT_VARIANT_OBJECT(wxIcon) + IMPLEMENT_VARIANT_OBJECT(wxBitmap) + @endcode + + Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from wxObject + and wxVariant no longer uses the type-unsafe wxList class for list + operations but the type-safe wxVariantList class. Also, wxVariantData now + supports the Clone function for implementing the wxVariant::Unshare function. + Clone is implemented automatically by IMPLEMENT_VARIANT_OBJECT. + + Since wxVariantData no longer derives from wxObject, any code that tests the + type + of the data using wxDynamicCast will require adjustment. You can use the macro + wxDynamicCastVariantData with the same arguments as wxDynamicCast, to use C++ + RTTI + type information instead of wxWidgets RTTI. + + @library{wxbase} + @category{data} + + @seealso + wxVariantData +*/ +class wxVariant : public wxObject +{ +public: + //@{ + /** + Construction from a ODBC timestamp value. Represented internally by a + wxDateTime value. + */ + wxVariant(); + wxVariant(const wxVariant& variant); + wxVariant(const wxChar* value, const wxString& name = ""); + wxVariant(const wxString& value, const wxString& name = ""); + wxVariant(wxChar value, const wxString& name = ""); + wxVariant(long value, const wxString& name = ""); + wxVariant(bool value, const wxString& name = ""); + wxVariant(double value, const wxString& name = ""); + wxVariant(const wxVariantList& value, + const wxString& name = ""); + wxVariant(void* value, const wxString& name = ""); + wxVariant(wxObject* value, const wxString& name = ""); + wxVariant(wxVariantData* data, const wxString& name = ""); + wxVariant(wxDateTime& val, const wxString& name = ""); + wxVariant(wxArrayString& val, const wxString& name = ""); + wxVariant(DATE_STRUCT* val, const wxString& name = ""); + wxVariant(TIME_STRUCT* val, const wxString& name = ""); + wxVariant(TIMESTAMP_STRUCT* val, const wxString& name = ""); + //@} + + /** + Destructor. + + Note that destructor is protected, so wxVariantData cannot usually + be deleted. Instead, wxVariantData::DecRef should be called. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxVariant(); + + /** + Appends a value to the list. + */ + void Append(const wxVariant& value); + + /** + Makes the variant null by deleting the internal data and + set the name to @e wxEmptyString. + */ + void Clear(); + + /** + Deletes the contents of the list. + */ + void ClearList(); + + //@{ + /** + Retrieves and converts the value of this variant to the type that @e value is. + */ + bool Convert(long* value); + bool Convert(bool* value); + bool Convert(double* value); + bool Convert(wxString* value); + bool Convert(wxChar* value); + bool Convert(wxDateTime* value); + //@} + + /** + Deletes the zero-based @e item from the list. + */ + bool Delete(size_t item); + + /** + Returns the string array value. + */ + wxArrayString GetArrayString(); + + /** + Returns the boolean value. + */ + bool GetBool(); + + /** + Returns the character value. + */ + wxChar GetChar(); + + /** + Returns the number of elements in the list. + */ + size_t GetCount(); + + /** + Returns a pointer to the internal variant data. To take ownership + of this data, you must call its wxVariantData::IncRef + method. When you stop using it, wxVariantData::DecRef + must be likewise called. + */ + wxVariantData* GetData(); + + /** + Returns the date value. + */ + wxDateTime GetDateTime(); + + /** + Returns the floating point value. + */ + double GetDouble(); + + /** + Returns a reference to the wxVariantList class used by + wxVariant if this wxVariant is currently a list of variants. + */ + wxVariantList GetList(); + + /** + Returns the integer value. + */ + long GetLong(); + + /** + Returns a constant reference to the variant name. + */ + const wxString GetName(); + + /** + Gets the string value. + */ + wxString GetString(); + + /** + Returns the value type as a string. The built-in types are: bool, char, + datetime, double, list, long, string, arrstring, void*. + + If the variant is null, the value type returned is the string "null" (not the + empty string). + */ + wxString GetType(); + + /** + Gets the void pointer value. + */ + void* GetVoidPtr(); + + /** + Gets the wxObject pointer value. + */ + wxObject* GetWxObjectPtr(); + + /** + Inserts a value at the front of the list. + */ + void Insert(const wxVariant& value); + + /** + Returns @true if there is no data associated with this variant, @false if there + is data. + */ + bool IsNull(); + + /** + Returns @true if @e type matches the type of the variant, @false otherwise. + */ + bool IsType(const wxString& type); + + /** + Returns @true if the data is derived from the class described by @e type, @false + otherwise. + */ + bool IsValueKindOf(const wxClassInfo* type type); + + /** + Makes the variant null by deleting the internal data. + */ + void MakeNull(); + + /** + Makes a string representation of the variant value (for any type). + */ + wxString MakeString(); + + /** + Returns @true if @e value matches an element in the list. + */ + bool Member(const wxVariant& value); + + /** + Makes an empty list. This differs from a null variant which has no data; a null + list + is of type list, but the number of elements in the list is zero. + */ + void NullList(); + + /** + Sets the internal variant data, deleting the existing data if there is any. + */ + void SetData(wxVariantData* data); + + /** + Makes sure that any data associated with this variant is not shared with other + variants. For this to work, wxVariantData::Clone must + be implemented for the data types you are working with. Clone is implemented + for all the default data types. + */ + bool Unshare(); + + //@{ + /** + Inequality test operators. + */ + bool operator !=(const wxVariant& value); + bool operator !=(const wxString& value); + bool operator !=(const wxChar* value); + bool operator !=(wxChar value); + bool operator !=(const long value); + bool operator !=(const bool value); + bool operator !=(const double value); + bool operator !=(void* value); + bool operator !=(wxObject* value); + bool operator !=(const wxVariantList& value); + bool operator !=(const wxArrayString& value); + bool operator !=(const wxDateTime& value); + //@} + + //@{ + /** + Assignment operators, using @ref overview_trefcount "reference counting" when + possible. + */ + void operator =(const wxVariant& value); + void operator =(wxVariantData* value); + void operator =(const wxString& value); + void operator =(const wxChar* value); + void operator =(wxChar value); + void operator =(const long value); + void operator =(const bool value); + void operator =(const double value); + void operator =(void* value); + void operator =(wxObject* value); + void operator =(const wxVariantList& value); + void operator =(const wxDateTime& value); + void operator =(const wxArrayString& value); + void operator =(const DATE_STRUCT* value); + void operator =(const TIME_STRUCT* value); + void operator =(const TIMESTAMP_STRUCT* value); + //@} + + //@{ + /** + Equality test operators. + */ + bool operator ==(const wxVariant& value); + bool operator ==(const wxString& value); + bool operator ==(const wxChar* value); + bool operator ==(wxChar value); + bool operator ==(const long value); + bool operator ==(const bool value); + bool operator ==(const double value); + bool operator ==(void* value); + bool operator ==(wxObject* value); + bool operator ==(const wxVariantList& value); + bool operator ==(const wxArrayString& value); + bool operator ==(const wxDateTime& value); + //@} + + //@{ + /** + Returns a reference to the value at @e idx (zero-based). This can be used + to change the value at this index. + */ + wxVariant operator [](size_t idx); + wxVariant operator [](size_t idx); + //@} + + //@{ + /** + Operator for implicit conversion to a long, using GetLong(). + */ + double operator double(); + long operator long(); + //@} + + /** + Operator for implicit conversion to a pointer to a void, using GetVoidPtr(). + */ + void* operator void*(); + + /** + Operator for implicit conversion to a wxChar, using GetChar(). + */ + char operator wxChar(); + + /** + Operator for implicit conversion to a pointer to a wxDateTime, using + GetDateTime(). + */ + void* operator wxDateTime(); + + /** + Operator for implicit conversion to a string, using MakeString(). + */ + wxString operator wxString(); +}; + + +/** + @class wxVariantData + @wxheader{variant.h} + + The @b wxVariantData class is used to implement a new type for wxVariant. + Derive from wxVariantData, and override the pure virtual functions. + + wxVariantData is @ref overview_refcount "reference counted", but you don't + normally have to care about this, + as wxVariant manages the count automatically. However, in case your application + needs to take + ownership of wxVariantData, be aware that the object is created with reference + count of 1, + and passing it to wxVariant will not increase this. In other words, + wxVariantData::IncRef + needs to be called only if you both take ownership of wxVariantData and pass it + to a wxVariant. + Also note that the destructor is protected, so you can never explicitly delete + a wxVariantData + instance. Instead, wxVariantData::DecRef will delete the object automatically + when the reference count reaches zero. + + @library{wxbase} + @category{FIXME} + + @seealso + wxVariant +*/ +class wxVariantData +{ +public: + /** + Default constructor. + */ + wxVariantData(); + + /** + This function can be overridden to clone the data. + Implement Clone if you wish wxVariant::Unshare to work + for your data. This function is implemented for all built-in data types. + */ + wxVariantData* Clone(); + + /** + Decreases reference count. If the count reaches zero, the object is + automatically deleted. + + Note that destructor of wxVariantData is protected, so delete + cannot be used as normal. Instead, DecRef() should be called. + */ + void DecRef(); + + /** + Returns @true if this object is equal to @e data. + */ +#define bool Eq(wxVariantData& data) /* implementation is private */ + + /** + Returns the string type of the data. + */ + wxString GetType(); + + /** + If the data is a wxObject returns a pointer to the objects wxClassInfo + structure, if + the data isn't a wxObject the method returns @NULL. + */ + wxClassInfo* GetValueClassInfo(); + + /** + Increases reference count. Note that initially wxVariantData has reference + count of 1. + */ + void IncRef(); + + //@{ + /** + Reads the data from @e stream or @e string. + */ + bool Read(ostream& stream); + bool Read(wxString& string); + //@} + + //@{ + /** + Writes the data to @e stream or @e string. + */ + bool Write(ostream& stream); + bool Write(wxString& string); + //@} + + /** + This macro returns the data stored in @e variant cast to the type @e classname + * if + the data is of this type (the check is done during the run-time) or + @NULL otherwise. + */ + classname * wxGetVariantCast(); +}; diff --git a/interface/vector.h b/interface/vector.h new file mode 100644 index 0000000000..3ca85c6c3e --- /dev/null +++ b/interface/vector.h @@ -0,0 +1,147 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: vector.h +// Purpose: documentation for wxVector class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxVectorT + @wxheader{vector.h} + + wxVectorT is a template class which implements most of the std::vector + class and can be used like it. If wxWidgets is compiled in STL mode, + wxVector will just be a typedef to std::vector. Just like for std::vector, + objects stored in wxVectorT need to be @e assignable but don't have to + be @e default constructible. + + You can refer to the STL documentation for further information. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxcontaineroverview "Container classes overview", wxListT, + wxArrayT +*/ +class wxVector +{ +public: + //@{ + /** + Constructor. + */ + wxVectorT(); + wxVectorT(const wxVector& c); + //@} + + /** + Destructor. + */ + ~wxVectorT(); + + //@{ + /** + Returns item at position @e idx. + */ + const value_type at(size_type idx); + value_type at(size_type idx); + //@} + + //@{ + /** + Return last item. + */ + const value_type back(); + value_type back(); + //@} + + //@{ + /** + Return iterator to beginning of the vector. + */ + const_iterator begin(); + iterator begin(); + //@} + + /** + + */ + size_type capacity(); + + /** + Clears the vector. + */ + void clear(); + + /** + Returns @true if the vector is empty. + */ + bool empty(); + + //@{ + /** + Returns iterator to the end of the vector. + */ + const_iterator end(); + iterator end(); + //@} + + //@{ + /** + Erase items. When using values other than built-in integrals + or classes with reference counting this can be an inefficient + operation. + */ + iterator erase(iterator it); + iterator erase(iterator first, iterator last); + //@} + + //@{ + /** + Returns first item. + */ + const value_type front(); + value_type front(); + //@} + + /** + ) + + Insert an item. When using values other than built-in integrals + or classes with reference counting this can be an inefficient + operation. + */ + iterator insert(iterator it); + + /** + Assignment operator. + */ + wxVectorT& operator operator=(const wxVector& vb); + + //@{ + /** + Returns item at position @e idx. + */ + const value_type operator[](size_type idx); + value_type operator[](size_type idx); + //@} + + /** + Removes the last item. + */ + void pop_back(); + + /** + Adds an item to the end of the vector. + */ + void push_back(const value_type& v); + + /** + Reserves more memory of @e n is greater then + wxVector::size. Other this call has + no effect. + */ + void reserve(size_type n); +}; diff --git a/interface/vlbox.h b/interface/vlbox.h new file mode 100644 index 0000000000..b172fe251a --- /dev/null +++ b/interface/vlbox.h @@ -0,0 +1,310 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: vlbox.h +// Purpose: documentation for wxVListBox class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxVListBox + @wxheader{vlbox.h} + + wxVListBox is a listbox-like control with the following two main differences + from a regular listbox: it can have an arbitrarily huge number of items because + it doesn't store them itself but uses wxVListBox::OnDrawItem + callback to draw them (so it is a Virtual listbox) and its items can + have variable height as determined by + wxVListBox::OnMeasureItem (so it is also a listbox + with the lines of Variable height). + + Also, as a consequence of its virtual nature, it doesn't have any methods to + append or insert items in it as it isn't necessary to do it: you just have to + call wxVListBox::SetItemCount to tell the control how + many items it should display. Of course, this also means that you will never + use this class directly because it has pure virtual functions, but will need to + derive your own class, such as wxHtmlListBox, from it. + + However it emits the same events as wxListBox and the same + event macros may be used with it. Since wxVListBox does not store its items + itself, the events will only contain the index, not any contents such as the + string of an item. + + @library{wxcore} + @category{ctrl} + @appearance{vlistbox.png} + + @seealso + wxSimpleHtmlListBox, wxHtmlListBox +*/ +class wxVListBox : public wxVScrolledWindow +{ +public: + //@{ + /** + Default constructor, you must call Create() later. + */ + wxVListBox(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + size_t countItems = 0, long style = 0, + const wxString& name = wxVListBoxNameStr); + wxVListBox(); + //@} + + /** + Deletes all items from the control. + */ + void Clear(); + + /** + Creates the control. To finish creating it you also should call + SetItemCount() to let it know about the + number of items it contains. + + The only special style which may be used with wxVListBox is @c wxLB_MULTIPLE + which indicates that the listbox should support multiple selection. + + Returns @true on success or @false if the control couldn't be created + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxVListBoxNameStr); + + /** + Deselects all the items in the listbox. + + Returns @true if any items were changed, i.e. if there had been any + selected items before, or @false if all the items were already deselected. + + This method is only valid for multi selection listboxes. + + @sa SelectAll(), Select() + */ + bool DeselectAll(); + + /** + Returns the index of the first selected item in the listbox or + @c wxNOT_FOUND if no items are currently selected. + + @e cookie is an opaque parameter which should be passed to the subsequent + calls to GetNextSelected(). It is needed in + order to allow parallel iterations over the selected items. + + Here is a typical example of using these functions: + + This method is only valid for multi selection listboxes. + */ + int GetFirstSelected(unsigned long& cookie); + + /** + Get the number of items in the control. + + @sa SetItemCount() + */ + size_t GetItemCount(); + + /** + Returns the margins used by the control. The @c x field of the returned + point is the horizontal margin and the @c y field is the vertical one. + + @sa SetMargins() + */ + wxPoint GetMargins(); + + /** + Returns the index of the next selected item or @c wxNOT_FOUND if there are + no more. + + This method is only valid for multi selection listboxes. + + @sa GetFirstSelected() + */ + int GetNextSelected(unsigned long& cookie); + + /** + Returns the number of the items currently selected. + + It is valid for both single and multi selection controls. In the former case it + may only return 0 or 1 however. + + @sa IsSelected(), GetFirstSelected(), + GetNextSelected() + */ + size_t GetSelectedCount(); + + /** + Get the currently selected item or @c wxNOT_FOUND if there is no selection. + */ + int GetSelection(); + + /** + Returns the background colour used for the selected cells. By default the + standard system colour is used. + + @sa wxSystemSettings::GetColour, SetSelectionBackground() + */ + const wxColour GetSelectionBackground(); + + /** + Returns @true if the listbox was created with @c wxLB_MULTIPLE style + and so supports multiple selection or @false if it is a single selection + listbox. + */ + bool HasMultipleSelection(); + + /** + Returns @true if this item is the current one, @false otherwise. + + Current item is always the same as selected one for the single selection + listbox and in this case this method is equivalent to + IsSelected() but they are different for multi + selection listboxes where many items may be selected but only one (at most) is + current. + */ + bool IsCurrent(size_t item); + + /** + Returns @true if this item is selected, @false otherwise. + */ + bool IsSelected(size_t item); + + /** + This method is used to draw the items background and, maybe, a border + around it. + + The base class version implements a reasonable default behaviour which + consists in drawing the selected item with the standard background + colour and drawing a border around the item if it is either selected or + current. + */ + void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n); + + /** + The derived class must implement this function to actually draw the item + with the given index on the provided DC. + + @param dc + The device context to use for drawing + + @param rect + The bounding rectangle for the item being drawn (DC clipping + region is set to this rectangle before calling this function) + + @param n + The index of the item to be drawn + */ + void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n); + + /** + This method may be used to draw separators between the lines. The rectangle + passed to it may be modified, typically to deflate it a bit before passing to + OnDrawItem(). + + The base class version of this method doesn't do anything. + + @param dc + The device context to use for drawing + + @param rect + The bounding rectangle for the item + + @param n + The index of the item + */ + void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n); + + /** + The derived class must implement this method to return the height of the + specified item (in pixels). + */ + wxCoord OnMeasureItem(size_t n); + + /** + Selects or deselects the specified item which must be valid (i.e. not + equal to @c wxNOT_FOUND). + + Return @true if the items selection status has changed or @false + otherwise. + + This function is only valid for the multiple selection listboxes, use + SetSelection() for the single selection ones. + */ + bool Select(size_t item, bool select = @true); + + /** + Selects all the items in the listbox. + + Returns @true if any items were changed, i.e. if there had been any + unselected items before, or @false if all the items were already selected. + + This method is only valid for multi selection listboxes. + + @sa DeselectAll(), Select() + */ + bool SelectAll(); + + /** + Selects all items in the specified range which may be given in any order. + + Return @true if the items selection status has changed or @false + otherwise. + + This method is only valid for multi selection listboxes. + + @sa SelectAll(), Select() + */ + bool SelectRange(size_t from, size_t to); + + /** + Set the number of items to be shown in the control. + + This is just a synonym for + wxVScrolledWindow::SetRowCount. + */ + void SetItemCount(size_t count); + + //@{ + /** + Set the margins: horizontal margin is the distance between the window + border and the item contents while vertical margin is half of the + distance between items. + + By default both margins are 0. + */ + void SetMargins(const wxPoint& pt); + void SetMargins(wxCoord x, wxCoord y); + //@} + + /** + Set the selection to the specified item, if it is -1 the selection is + unset. The selected item will be automatically scrolled into view if it isn't + currently visible. + + This method may be used both with single and multiple selection listboxes. + */ + void SetSelection(int selection); + + /** + Sets the colour to be used for the selected cells background. The background of + the standard cells may be changed by simply calling + wxWindow::SetBackgroundColour. + + Notice that using non-default background colour may result in control having + appearance different from the similar native controls and so should in general + be avoided. + + @sa GetSelectionBackground() + */ + void SetSelectionBackground(const wxColour& col); + + /** + Toggles the state of the specified @e item, i.e. selects it if it was + unselected and deselects it if it was selected. + + This method is only valid for multi selection listboxes. + */ + void Toggle(size_t item); +}; diff --git a/interface/vscroll.h b/interface/vscroll.h new file mode 100644 index 0000000000..f7d554e6d7 --- /dev/null +++ b/interface/vscroll.h @@ -0,0 +1,887 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: vscroll.h +// Purpose: documentation for wxVarHScrollHelper class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxVarHScrollHelper + @wxheader{vscroll.h} + + This class provides functions wrapping the + wxVarScrollHelperBase class, targeted for + horizontal-specific scrolling using wxHScrolledWindow. + + Like wxVarScrollHelperBase, this class is mostly only useful to those classes + built into wxWidgets deriving from here, and this documentation is mostly + only provided for referencing those functions provided. You will likely want + to derive your window from wxHScrolledWindow rather than from here directly. + + @library{wxcore} + @category{FIXME} + + @seealso + wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxVarHScrollHelper : public wxVarScrollHelperBase +{ +public: + /** + Constructor taking the target window to be scrolled by this helper class. + This will attach scroll event handlers to the target window to catch and + handle scroll events appropriately. + */ + wxVarHScrollHelper(wxWindow* winToScroll); + + /** + This class forwards calls from + wxVarScrollHelperBase::EstimateTotalSize + to this function so derived classes can override either just the height or + the width estimation, or just estimate both differently if desired in any + wxHVScrolledWindow derived class. + + Please note that this function will not be called if @c EstimateTotalSize() + is overridden in your derived class. + */ + virtual wxCoord EstimateTotalWidth(); + + /** + Returns the number of columns the target window contains. + + @sa SetColumnCount() + */ + size_t GetColumnCount(); + + /** + Returns the index of the first visible column based on the scroll position. + */ + size_t GetVisibleColumnsBegin(); + + /** + Returns the index of the last visible column based on the scroll position. This + includes the last column even if it is only partially visible. + */ + size_t GetVisibleColumnsEnd(); + + /** + Returns @true if the given column is currently visible (even if only + partially visible) or @false otherwise. + */ + bool IsColumnVisible(size_t column); + + /** + This function must be overridden in the derived class, and should return the + width of the given column in pixels. + */ + virtual wxCoord OnGetColumnWidth(size_t column); + + /** + This function doesn't have to be overridden but it may be useful to do so if + calculating the columns' sizes is a relatively expensive operation as it gives + your code a chance to calculate several of them at once and cache the result + if necessary. + + @c OnGetColumnsWidthHint() is normally called just before + OnGetColumnWidth() but you + shouldn't rely on the latter being called for all columns in the interval + specified here. It is also possible that OnGetColumnWidth() will be called for + units outside of this interval, so this is really just a hint, not a promise. + + Finally, note that columnMin is inclusive, while columnMax is exclusive. + */ + virtual void OnGetColumnsWidthHint(size_t columnMin, + size_t columnMax); + + /** + Triggers a refresh for just the given column's area of the window if it's + visible. + */ + virtual void RefreshColumn(size_t column); + + /** + Triggers a refresh for the area between the specified range of columns given + (inclusively). + */ + virtual void RefreshColumns(size_t from, size_t to); + + /** + Scroll by the specified number of pages which may be positive (to scroll right) + or negative (to scroll left). + */ + virtual bool ScrollColumnPages(int pages); + + /** + Scroll by the specified number of columns which may be positive (to scroll + right) + or negative (to scroll left). + + Returns @true if the window was scrolled, @false otherwise (for + example, if we're trying to scroll right but we are already showing the last + column). + */ + virtual bool ScrollColumns(int columns); + + /** + Scroll to the specified column. It will become the first visible column in the + window. + + Returns @true if we scrolled the window, @false if nothing was done. + */ + bool ScrollToColumn(size_t column); + + /** + Set the number of columns the window contains. The derived class must provide + the widths for all columns with indices up to the one given here in it's + OnGetColumnWidth() implementation. + */ + void SetColumnCount(size_t columnCount); +}; + + +/** + @class wxVarVScrollHelper + @wxheader{vscroll.h} + + This class provides functions wrapping the + wxVarScrollHelperBase class, targeted for + vertical-specific scrolling using wxVScrolledWindow. + + Like wxVarScrollHelperBase, this class is mostly only useful to those classes + built into wxWidgets deriving from here, and this documentation is mostly + only provided for referencing those functions provided. You will likely want + to derive your window from wxVScrolledWindow rather than from here directly. + + @library{wxcore} + @category{FIXME} + + @seealso + wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxVarVScrollHelper : public wxVarScrollHelperBase +{ +public: + /** + Constructor taking the target window to be scrolled by this helper class. + This will attach scroll event handlers to the target window to catch and + handle scroll events appropriately. + */ + wxVarVScrollHelper(wxWindow* winToScroll); + + /** + This class forwards calls from + wxVarScrollHelperBase::EstimateTotalSize + to this function so derived classes can override either just the height or + the width estimation, or just estimate both differently if desired in any + wxHVScrolledWindow derived class. + + Please note that this function will not be called if @c EstimateTotalSize() + is overridden in your derived class. + */ + virtual wxCoord EstimateTotalHeight(); + + /** + Returns the number of rows the target window contains. + + @sa SetRowCount() + */ + size_t GetRowCount(); + + /** + Returns the index of the first visible row based on the scroll position. + */ + size_t GetVisibleRowsBegin(); + + /** + Returns the index of the last visible row based on the scroll position. This + includes the last row even if it is only partially visible. + */ + size_t GetVisibleRowsEnd(); + + /** + Returns @true if the given row is currently visible (even if only + partially visible) or @false otherwise. + */ + bool IsRowVisible(size_t row); + + /** + This function must be overridden in the derived class, and should return the + height of the given row in pixels. + */ + virtual wxCoord OnGetRowHeight(size_t row); + + /** + This function doesn't have to be overridden but it may be useful to do so if + calculating the rows' sizes is a relatively expensive operation as it gives + your code a chance to calculate several of them at once and cache the result + if necessary. + + @c OnGetRowsHeightHint() is normally called just before + OnGetRowHeight() but you + shouldn't rely on the latter being called for all rows in the interval + specified here. It is also possible that OnGetRowHeight() will be called for + units outside of this interval, so this is really just a hint, not a promise. + + Finally, note that rowMin is inclusive, while rowMax is exclusive. + */ + virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax); + + /** + Triggers a refresh for just the given row's area of the window if it's visible. + */ + virtual void RefreshRow(size_t row); + + /** + Triggers a refresh for the area between the specified range of rows given + (inclusively). + */ + virtual void RefreshRows(size_t from, size_t to); + + /** + Scroll by the specified number of pages which may be positive (to scroll down) + or negative (to scroll up). + */ + virtual bool ScrollRowPages(int pages); + + /** + Scroll by the specified number of rows which may be positive (to scroll down) + or negative (to scroll up). + + Returns @true if the window was scrolled, @false otherwise (for + example, if we're trying to scroll down but we are already showing the last + row). + */ + virtual bool ScrollRows(int rows); + + /** + Scroll to the specified row. It will become the first visible row in the window. + + Returns @true if we scrolled the window, @false if nothing was done. + */ + bool ScrollToRow(size_t row); + + /** + Set the number of rows the window contains. The derived class must provide the + heights for all rows with indices up to the one given here in it's + OnGetRowHeight() implementation. + */ + void SetRowCount(size_t rowCount); +}; + + +/** + @class wxVarScrollHelperBase + @wxheader{vscroll.h} + + This class provides all common base functionality for scroll calculations + shared among all variable scrolled window implementations as well as + automatic scrollbar functionality, saved scroll positions, controlling + target windows to be scrolled, as well as defining all required virtual + functions that need to be implemented for any orientation specific work. + + Documentation of this class is provided specifically for referencing use + of the functions provided by this class for use with the variable scrolled + windows that derive from here. You will likely want to derive your window + from one of the already implemented variable scrolled windows rather than + from wxVarScrollHelperBase directly. + + @library{wxcore} + @category{FIXME} + + @seealso + wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxVarScrollHelperBase +{ +public: + /** + Constructor taking the target window to be scrolled by this helper class. + This will attach scroll event handlers to the target window to catch and + handle scroll events appropriately. + */ + wxVarScrollHelperBase(wxWindow* winToScroll); + + /** + Virtual destructor for detaching scroll event handlers attached with this + helper class. + */ + ~wxVarScrollHelperBase(); + + /** + Translates the logical coordinate given to the current device coordinate. + For example, if the window is scrolled 10 units and each scroll unit + represents 10 device units (which may not be the case since this class allows + for variable scroll unit sizes), a call to this function with a coordinate of + 15 will return -85. + + @sa CalcUnscrolledPosition() + */ + int CalcScrolledPosition(int coord); + + /** + Translates the device coordinate given to the corresponding logical + coordinate. For example, if the window is scrolled 10 units and each scroll + unit represents 10 device units (which may not be the case since this class + allows for variable scroll unit sizes), a call to this function with a + coordinate of 15 will return 115. + + @sa CalcScrolledPosition() + */ + int CalcUnscrolledPosition(int coord); + + /** + With physical scrolling on (when this is @true), the device origin is + changed properly when a wxPaintDC is prepared, + children are actually moved and laid out properly, and the contents of the + window (pixels) are actually moved. When this is @false, you are + responsible for repainting any invalidated areas of the window yourself to + account for the new scroll position. + */ + void EnablePhysicalScrolling(bool scrolling = @true); + + /** + When the number of scroll units change, we try to estimate the total size of + all units when the full window size is needed (i.e. to calculate the scrollbar + thumb size). This is a rather expensive operation in terms of unit access, so + if the user code may estimate the average size better or faster than we do, it + should override this function to implement its own logic. This function should + return the best guess for the total virtual window size. + + Note that although returning a totally wrong value would still work, it risks + resulting in very strange scrollbar behaviour so this function should really + try to make the best guess possible. + */ + virtual wxCoord EstimateTotalSize(); + + /** + This function needs to be overridden in the in the derived class to return the + window size with respect to the opposing orientation. If this is a vertical + scrolled window, it should return the height. + + @sa GetOrientationTargetSize() + */ + virtual int GetNonOrientationTargetSize(); + + /** + This function need to be overridden to return the orientation that this helper + is working with, either @c wxHORIZONTAL or @c wxVERTICAL. + */ + virtual wxOrientation GetOrientation(); + + /** + This function needs to be overridden in the in the derived class to return the + window size with respect to the orientation this helper is working with. If + this is a vertical scrolled window, it should return the width. + + @sa GetNonOrientationTargetSize() + */ + virtual int GetOrientationTargetSize(); + + /** + This function will return the target window this helper class is currently + scrolling. + + @sa SetTargetWindow() + */ + wxWindow* GetTargetWindow(); + + /** + Returns the index of the first visible unit based on the scroll position. + */ + size_t GetVisibleBegin(); + + /** + Returns the index of the last visible unit based on the scroll position. This + includes the last unit even if it is only partially visible. + */ + size_t GetVisibleEnd(); + + /** + Returns @true if the given scroll unit is currently visible (even if only + partially visible) or @false otherwise. + */ + bool IsVisible(size_t unit); + + /** + This function must be overridden in the derived class, and should return the + size of the given unit in pixels. + */ + virtual wxCoord OnGetUnitSize(size_t unit); + + /** + This function doesn't have to be overridden but it may be useful to do so if + calculating the units' sizes is a relatively expensive operation as it gives + your code a chance to calculate several of them at once and cache the result + if necessary. + + @c OnGetUnitsSizeHint() is normally called just before + OnGetUnitSize() but you + shouldn't rely on the latter being called for all units in the interval + specified here. It is also possible that OnGetUnitSize() will be called for + units outside of this interval, so this is really just a hint, not a promise. + + Finally, note that unitMin is inclusive, while unitMax is exclusive. + */ + virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax); + + /** + Recalculate all parameters and repaint all units. + */ + virtual void RefreshAll(); + + /** + Normally the window will scroll itself, but in some rare occasions you might + want it to scroll (part of) another window (e.g. a child of it in order to + scroll only a portion the area between the scrollbars like a spreadsheet where + only the cell area will move). + + @sa GetTargetWindow() + */ + void SetTargetWindow(wxWindow* target); + + /** + Update the thumb size shown by the scrollbar. + */ + virtual void UpdateScrollbar(); + + /** + Returns the virtual scroll unit under the device unit given accounting for + scroll position or @c wxNOT_FOUND if none (i.e. if it is below the last + item). + */ + int VirtualHitTest(wxCoord coord); +}; + + +/** + @class wxVScrolledWindow + @wxheader{vscroll.h} + + In the name of this class, "V" may stand for "variable" because it can be + used for scrolling rows of variable heights; "virtual", because it is not + necessary to know the heights of all rows in advance -- only those which + are shown on the screen need to be measured; or even "vertical", because + this class only supports scrolling vertically. + + In any case, this is a generalization of the + wxScrolledWindow class which can be only used when + all rows have the same heights. It lacks some other wxScrolledWindow features + however, notably it can't scroll only a rectangle of the window and not its + entire client area. + + To use this class, you need to derive from it and implement the + wxVarVScrollHelper::OnGetRowHeight pure virtual + method. You also must call wxVarVScrollHelper::SetRowCount + to let the base class know how many rows it should display, but from that + moment on the scrolling is handled entirely by wxVScrolledWindow. You only + need to draw the visible part of contents in your @c OnPaint() method as + usual. You should use wxVarVScrollHelper::GetVisibleRowsBegin + and wxVarVScrollHelper::GetVisibleRowsEnd to + select the lines to display. Note that the device context origin is not shifted + so the first visible row always appears at the point (0, 0) in physical as + well as logical coordinates. + + @library{wxcore} + @category{miscwnd} + + @seealso + wxHScrolledWindow, wxHVScrolledWindow +*/ +class wxVScrolledWindow : public wxPanel +{ +public: + //@{ + /** + This is the normal constructor, no need to call @c Create() after using this + one. + + Note that @c wxVSCROLL is always automatically added to our style, there is + no need to specify it explicitly. + + @param parent + The parent window, must not be @NULL + + @param id + The identifier of this window, wxID_ANY by default + + @param pos + The initial window position + + @param size + The initial window size + + @param style + The window style. There are no special style bits defined for + this class. + + @param name + The name for this window; usually not used + */ + wxVScrolledWindow(); + wxVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPanelNameStr); + //@} + + /** + Same as the @ref wxvscrolledwindow() "non-default constuctor" + but returns status code: @true if ok, @false if the window couldn't + be created. + + Just as with the constructor above, the @c wxVSCROLL style is always used, + there is no need to specify it explicitly. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPanelNameStr); + + //@{ + /** + The following functions provide backwards compatibility for applications + originally built using wxVScrolledWindow in 2.6 or 2.8. Originally, + wxVScrolledWindow referred to scrolling "lines". We now use "units" in + wxVarScrollHelperBase to avoid implying any orientation (since the functions + are used for both horizontal and vertical scrolling in derived classes). And + in the new wxVScrolledWindow and wxHScrolledWindow classes, we refer to them + as "rows" and "columns", respectively. This is to help clear some confusion + in not only those classes, but also in wxHVScrolledWindow where functions + are inherited from both. + + You are encouraged to update any existing code using these function to use + the new replacements mentioned below, and avoid using these functions for + any new code as they are deprecated. + + Deprecated for wxVarVScrollHelper::SetRowCount. + */ + size_t GetFirstVisibleLine(); + size_t GetLastVisibleLine(); + size_t GetLineCount(); + int HitTest(wxCoord x, wxCoord y); + int HitTest(const wxPoint& pt); + virtual wxCoord OnGetLineHeight(size_t line); + virtual void OnGetLinesHint(size_t lineMin, size_t lineMax); + virtual void RefreshLine(size_t line); + virtual void RefreshLines(size_t from, size_t to); + virtual bool ScrollLines(int lines); + virtual bool ScrollPages(int pages); + bool ScrollToLine(size_t line); + void SetLineCount(size_t count); + //@} +}; + + +/** + @class wxHVScrolledWindow + @wxheader{vscroll.h} + + This window inherits all functionality of both vertical and horizontal, + variable scrolled windows. It automatically handles everything needed to + scroll both axis simultaneously with both variable row heights and variable + column widths. + + This is a generalization of the wxScrolledWindow + class which can be only used when all rows and columns are the same size. It + lacks some other wxScrolledWindow features however, notably it can't scroll + only a rectangle of the window and not its entire client area. + + To use this class, you must derive from it and implement both the + wxVarVScrollHelper::OnGetRowHeight and + wxVarHScrollHelper::OnGetColumnWidth pure virtual + methods to let the base class know how many rows and columns it should + display. You also need to set the total rows and columns the window contains, + but from that moment on the scrolling is handled entirely by + wxHVScrolledWindow. You only need to draw the visible part of contents in + your @c OnPaint() method as usual. You should use + wxVarHVScrollHelper::GetVisibleBegin + and wxVarHVScrollHelper::GetVisibleEnd to select the + lines to display. Note that the device context origin is not shifted so the + first visible row and column always appear at the point (0, 0) in physical + as well as logical coordinates. + + @library{wxcore} + @category{FIXME} + + @seealso + wxHScrolledWindow, wxVScrolledWindow +*/ +class wxHVScrolledWindow : public wxPanel +{ +public: + //@{ + /** + This is the normal constructor, no need to call @c Create() after using this + one. + + Note that @c wxHSCROLL and @c wxVSCROLL are always automatically added + to our styles, there is no need to specify it explicitly. + + @param parent + The parent window, must not be @NULL + + @param id + The identifier of this window, wxID_ANY by default + + @param pos + The initial window position + + @param size + The initial window size + + @param style + The window style. There are no special style bits defined for + this class. + + @param name + The name for this window; usually not used + */ + wxHVScrolledWindow(); + wxHVScrolledWindow(wxWindow* parent, + wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPanelNameStr); + //@} + + /** + Same as the @ref wxhvscrolledwindow() "non-default constuctor" + but returns status code: @true if ok, @false if the window couldn't + be created. + + Just as with the constructor above, the @c wxHSCROLL and @c wxVSCROLL + styles are always used, there is no need to specify it explicitly. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPanelNameStr); +}; + + +/** + @class wxVarHVScrollHelper + @wxheader{vscroll.h} + + This class provides functions wrapping the + wxVarHScrollHelper and + wxVarVScrollHelper classes, targeted for + scrolling a window in both axis using + wxHVScrolledWindow. Since this class is also + the join class of the horizontal and vertical scrolling functionality, it + also addresses some wrappers that help avoid the need to specify class scope + in your wxHVScrolledWindow-derived class when using wxVarScrollHelperBase + functionality. + + Like all three of it's scroll helper base classes, this class is mostly only + useful to those classes built into wxWidgets deriving from here, and this + documentation is mostly only provided for referencing those functions + provided. You will likely want to derive your window from wxHVScrolledWindow + rather than from here directly. + + @library{wxcore} + @category{FIXME} + + @seealso + wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxVarHVScrollHelper : public wxVarVScrollHelper +{ +public: + /** + Constructor taking the target window to be scrolled by this helper class. + This will attach scroll event handlers to the target window to catch and + handle scroll events appropriately. + */ + wxVarHVScrollHelper(wxWindow* winToScroll); + + /** + With physical scrolling on (when this is @true), the device origin is + changed properly when a wxPaintDC is prepared, + children are actually moved and laid out properly, and the contents of the + window (pixels) are actually moved. When this is @false, you are + responsible for repainting any invalidated areas of the window yourself to + account for the new scroll position. + + @param vscrolling + Specifies if physical scrolling should be turned on when scrolling vertically. + + @param hscrolling + Specifies if physical scrolling should be turned on when scrolling horizontally. + */ + void EnablePhysicalScrolling(bool vscrolling = @true, + bool hscrolling = @true); + + /** + Returns the number of columns and rows the target window contains. + + @sa SetRowColumnCount() + */ + wxSize GetRowColumnCount(); + + /** + Returns the index of the first visible column and row based on the current + scroll position. + */ + wxPosition GetVisibleBegin(); + + /** + Returns the index of the last visible column and row based on the scroll + position. This includes any partially visible columns or rows. + */ + wxPosition GetVisibleEnd(); + + //@{ + /** + Returns @true if both the given row and column are currently visible + (even if only partially visible) or @false otherwise. + */ + bool IsVisible(size_t row, size_t column); + bool IsVisible(const wxPosition& pos); + //@} + + //@{ + /** + Triggers a refresh for just the area shared between the given row and column + of the window if it is visible. + */ + virtual void RefreshRowColumn(size_t row, size_t column); + virtual void RefreshRowColumn(const wxPosition& pos); + //@} + + //@{ + /** + Triggers a refresh for the visible area shared between all given rows and + columns (inclusive) of the window. If the target window for both orientations + is the same, the rectangle of cells is refreshed; if the target windows + differ, the entire client size opposite the orientation direction is + refreshed between the specified limits. + */ + virtual void RefreshRowsColumns(size_t fromRow, size_t toRow, + size_t fromColumn, + size_t toColumn); + virtual void RefreshRowsColumns(const wxPosition& from, + const wxPosition& to); + //@} + + //@{ + /** + Scroll to the specified row and column. It will become the first visible row + and column in the window. Returns @true if we scrolled the window, + @false if nothing was done. + */ + bool ScrollToRowColumn(size_t row, size_t column); + bool ScrollToRowColumn(const wxPosition& pos); + //@} + + /** + Set the number of rows and columns the target window will contain. The + derived class must provide the sizes for all rows and columns with indices up + to the ones given here in it's wxVarVScrollHelper::OnGetRowHeight + and wxVarHScrollHelper::OnGetColumnWidth implementations, + respectively. + */ + void SetRowColumnCount(size_t rowCount, size_t columnCount); + + //@{ + /** + Returns the virtual scroll unit under the device unit given accounting for + scroll position or @c wxNOT_FOUND (for the row, column, or possibly both + values) if none. + */ + wxPosition VirtualHitTest(wxCoord x, wxCoord y); + wxPosition VirtualHitTest(const wxPoint& pos); + //@} +}; + + +/** + @class wxHScrolledWindow + @wxheader{vscroll.h} + + In the name of this class, "H" stands for "horizontal" because it can be + used for scrolling columns of variable widths. It is not necessary to know + the widths of all columns in advance -- only those which are shown on the + screen need to be measured. + + In any case, this is a generalization of the + wxScrolledWindow class which can be only used when + all columns have the same widths. It lacks some other wxScrolledWindow features + however, notably it can't scroll only a rectangle of the window and not its + entire client area. + + To use this class, you need to derive from it and implement the + wxVarHScrollHelper::OnGetColumnWidth pure virtual + method. You also must call wxVarHScrollHelper::SetColumnCount + to let the base class know how many columns it should display, but from that + moment on the scrolling is handled entirely by wxHScrolledWindow. You only + need to draw the visible part of contents in your @c OnPaint() method as + usual. You should use wxVarHScrollHelper::GetVisibleColumnsBegin + and wxVarHScrollHelper::GetVisibleColumnsEnd to + select the lines to display. Note that the device context origin is not shifted + so the first visible column always appears at the point (0, 0) in physical as + well as logical coordinates. + + @library{wxcore} + @category{FIXME} + + @seealso + wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxHScrolledWindow : public wxPanel +{ +public: + //@{ + /** + This is the normal constructor, no need to call @c Create() after using this + one. + + Note that @c wxHSCROLL is always automatically added to our style, there is + no need to specify it explicitly. + + @param parent + The parent window, must not be @NULL + + @param id + The identifier of this window, wxID_ANY by default + + @param pos + The initial window position + + @param size + The initial window size + + @param style + The window style. There are no special style bits defined for + this class. + + @param name + The name for this window; usually not used + */ + wxHScrolledWindow(); + wxHScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPanelNameStr); + //@} + + /** + Same as the @ref wxhscrolledwindow() "non-default constuctor" + but returns status code: @true if ok, @false if the window couldn't + be created. + + Just as with the constructor above, the @c wxHSCROLL style is always used, + there is no need to specify it explicitly. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPanelNameStr); +}; diff --git a/interface/weakref.h b/interface/weakref.h new file mode 100644 index 0000000000..96eabd5d23 --- /dev/null +++ b/interface/weakref.h @@ -0,0 +1,123 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: weakref.h +// Purpose: documentation for wxWeakRefDynamic class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWeakRefDynamicT + @wxheader{weakref.h} + + wxWeakRefDynamicT is a template class for weak references that is used in + the same way as wxWeakRefT. The only difference is that wxWeakRefDynamic + defaults to using @c dynamic_cast for establishing the object + reference (while wxWeakRef defaults to @c static_cast). + + So, wxWeakRef will detect a type mismatch during compile time and will + have a little better run-time performance. The role of wxWeakRefDynamic + is to handle objects which derived type one does not know. + + @b Note: wxWeakRefT selects an implementation based on the static type + of T. If T does not have wxTrackable statically, it defaults to to a mixed- + mode operation, where it uses @c dynamic_cast as the last measure (if + available from the compiler and enabled when building wxWidgets). + + For general cases, wxWeakRefT is the better choice. + + For API documentation, see: wxWeakRef + + @library{wxcore} + @category{FIXME} +*/ +class wxWeakRefDynamic +{ +public: + +}; + + +/** + @class wxWeakRefT + @wxheader{weakref.h} + + wxWeakRef is a template class for weak references to wxWidgets objects, + such as wxEvtHandler, wxWindow and + wxObject. A weak reference behaves much like an ordinary + pointer, but when the object pointed is destroyed, the weak reference is + automatically reset to a @NULL pointer. + + wxWeakRefT can be used whenever one must keep a pointer to an object + that one does not directly own, and that may be destroyed before the object + holding the reference. + + wxWeakRefT is a small object and the mechanism behind it is fast + (@b O(1)). So the overall cost of using it is small. + + @library{wxbase} + @category{FIXME} + + @seealso + wxSharedPtr, wxScopedPtr +*/ +class wxWeakRef +{ +public: + /** + Constructor. The weak reference is initialized to @e pobj. + */ + wxWeakRefT(T* pobj = @NULL); + + /** + Destructor. + */ + ~wxWeakRefT(); + + /** + Called when the tracked object is destroyed. Be default sets + internal pointer to @NULL. + */ + virtual void OnObjectDestroy(); + + /** + Release currently tracked object and rests object reference. + */ + void Release(); + + /** + Returns pointer to the tracked object or @NULL. + */ + T * get(); + + /** + Release currently tracked object and start tracking the same object as + the wxWeakRef @e wr. + */ + T* operator =(wxWeakRef& wr); + + /** + Implicit conversion to T*. Returns pointer to the tracked + object or @NULL. + */ + T* operator*(); + + /** + Returns a reference to the tracked object. If the internal pointer is @NULL + this method will cause an assert in debug mode. + */ + T operator*(); + + /** + Smart pointer member access. Returns a pointer to the + tracked object. If the internal pointer is @NULL this + method will cause an assert in debug mode. + */ + T* operator-(); + + /** + Releases the currently tracked object and starts tracking @e pobj. + A weak reference may be reset by passing @e @NULL as @e pobj. + */ + T* operator=(T* pobj); +}; diff --git a/interface/wfstream.h b/interface/wfstream.h new file mode 100644 index 0000000000..ec346a8039 --- /dev/null +++ b/interface/wfstream.h @@ -0,0 +1,270 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wfstream.h +// Purpose: documentation for wxTempFileOutputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTempFileOutputStream + @wxheader{wfstream.h} + + wxTempFileOutputStream is an output stream based on wxTempFile. It + provides a relatively safe way to replace the contents of the + existing file. + + @library{wxbase} + @category{streams} + + @seealso + wxTempFile +*/ +class wxTempFileOutputStream : public wxOutputStream +{ +public: + /** + Associates wxTempFileOutputStream with the file to be replaced and opens it. + You should use + wxStreamBase::IsOk to verify if the constructor succeeded. + + Call Commit() or wxOutputStream::Close to + replace the old file and close this one. Calling Discard() + (or allowing the destructor to do it) will discard the changes. + */ + wxTempFileOutputStream(const wxString& fileName); + + /** + Validate changes: deletes the old file of the given name and renames the new + file to the old name. Returns @true if both actions succeeded. If @false is + returned it may unfortunately mean two quite different things: either that + either the old file couldn't be deleted or that the new file couldn't be renamed + to the old name. + */ + bool Commit(); + + /** + Discard changes: the old file contents are not changed, the temporary file is + deleted. + */ + void Discard(); +}; + + +/** + @class wxFFileOutputStream + @wxheader{wfstream.h} + + This class represents data written to a file. There are actually + two such groups of classes: this one is based on wxFFile + whereas wxFileInputStream is based in + the wxFile class. + + Note that wxOutputStream::SeekO + can seek beyond the end of the stream (file) and will thus not return + @e wxInvalidOffset for that. + + @library{wxbase} + @category{streams} + + @seealso + wxBufferedOutputStream, wxFFileInputStream, wxFileInputStream +*/ +class wxFFileOutputStream : public wxOutputStream +{ +public: + //@{ + /** + Initializes a file stream in write-only mode using the file descriptor @e fp. + */ + wxFFileOutputStream(const wxString& filename, + const wxString& mode="w+b"); + wxFFileOutputStream(wxFFile& file); + wxFFileOutputStream(FILE * fp); + //@} + + /** + Destructor. + */ + ~wxFFileOutputStream(); + + /** + Returns @true if the stream is initialized and ready. + */ +#define bool IsOk() /* implementation is private */ +}; + + +/** + @class wxFileOutputStream + @wxheader{wfstream.h} + + This class represents data written to a file. There are actually + two such groups of classes: this one is based on wxFile + whereas wxFFileInputStream is based in + the wxFFile class. + + Note that wxOutputStream::SeekO + can seek beyond the end of the stream (file) and will thus not return + @e wxInvalidOffset for that. + + @library{wxbase} + @category{streams} + + @seealso + wxBufferedOutputStream, wxFileInputStream, wxFFileInputStream +*/ +class wxFileOutputStream : public wxOutputStream +{ +public: + //@{ + /** + Initializes a file stream in write-only mode using the file descriptor @e fd. + */ + wxFileOutputStream(const wxString& ofileName); + wxFileOutputStream(wxFile& file); + wxFileOutputStream(int fd); + //@} + + /** + Destructor. + */ + ~wxFileOutputStream(); + + /** + Returns @true if the stream is initialized and ready. + */ +#define bool IsOk() /* implementation is private */ +}; + + +/** + @class wxFileInputStream + @wxheader{wfstream.h} + + This class represents data read in from a file. There are actually + two such groups of classes: this one is based on wxFile + whereas wxFFileInputStream is based in + the wxFFile class. + + Note that wxInputStream::SeekI + can seek beyond the end of the stream (file) and will thus not return + @e wxInvalidOffset for that. + + @library{wxbase} + @category{streams} + + @seealso + wxBufferedInputStream, wxFileOutputStream, wxFFileOutputStream +*/ +class wxFileInputStream : public wxInputStream +{ +public: + //@{ + /** + Initializes a file stream in read-only mode using the specified file descriptor. + */ + wxFileInputStream(const wxString& ifileName); + wxFileInputStream(wxFile& file); + wxFileInputStream(int fd); + //@} + + /** + Destructor. + */ + ~wxFileInputStream(); + + /** + Returns @true if the stream is initialized and ready. + */ +#define bool IsOk() /* implementation is private */ +}; + + +/** + @class wxFFileInputStream + @wxheader{wfstream.h} + + This class represents data read in from a file. There are actually + two such groups of classes: this one is based on wxFFile + whereas wxFileInputStream is based in + the wxFile class. + + Note that wxInputStream::SeekI + can seek beyond the end of the stream (file) and will thus not return + @e wxInvalidOffset for that. + + @library{wxbase} + @category{streams} + + @seealso + wxBufferedInputStream, wxFFileOutputStream, wxFileOutputStream +*/ +class wxFFileInputStream : public wxInputStream +{ +public: + //@{ + /** + Initializes a file stream in read-only mode using the specified file pointer @e + fp. + */ + wxFFileInputStream(const wxString& filename, + const wxString& mode = "rb"); + wxFFileInputStream(wxFFile& file); + wxFFileInputStream(FILE * fp); + //@} + + /** + Destructor. + */ + ~wxFFileInputStream(); + + /** + Returns @true if the stream is initialized and ready. + */ +#define bool IsOk() /* implementation is private */ +}; + + +/** + @class wxFFileStream + @wxheader{wfstream.h} + + + @library{wxbase} + @category{FIXME} + + @seealso + wxStreamBuffer +*/ +class wxFFileStream : public wxFFileOutputStream +{ +public: + /** + Initializes a new file stream in read-write mode using the specified + @e iofilename name. + */ + wxFFileStream(const wxString& iofileName); +}; + + +/** + @class wxFileStream + @wxheader{wfstream.h} + + + @library{wxbase} + @category{FIXME} + + @seealso + wxStreamBuffer +*/ +class wxFileStream : public wxFileOutputStream +{ +public: + /** + Initializes a new file stream in read-write mode using the specified + @e iofilename name. + */ + wxFileStream(const wxString& iofileName); +}; diff --git a/interface/window.h b/interface/window.h new file mode 100644 index 0000000000..3310828e81 --- /dev/null +++ b/interface/window.h @@ -0,0 +1,2748 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: window.h +// Purpose: documentation for wxWindow class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWindow + @wxheader{window.h} + + wxWindow is the base class for all windows and represents any visible object on + screen. All controls, top level windows and so on are windows. Sizers and + device contexts are not, however, as they don't appear on screen themselves. + + Please note that all children of the window will be deleted automatically by + the destructor before the window itself is deleted which means that you don't + have to worry about deleting them manually. Please see the @ref + overview_windowdeletionoverview "window + deletion overview" for more information. + + Also note that in this, and many others, wxWidgets classes some + @c GetXXX() methods may be overloaded (as, for example, + wxWindow::GetSize or + wxWindow::GetClientSize). In this case, the overloads + are non-virtual because having multiple virtual functions with the same name + results in a virtual function name hiding at the derived class level (in + English, this means that the derived class has to override all overloaded + variants if it overrides any of them). To allow overriding them in the derived + class, wxWidgets uses a unique protected virtual @c DoGetXXX() method + and all @c GetXXX() ones are forwarded to it, so overriding the former + changes the behaviour of the latter. + + @beginStyleTable + @style{wxBORDER_DEFAULT}: + The window class will decide the kind of border to show, if any. + @style{wxBORDER_SIMPLE}: + Displays a thin border around the window. wxSIMPLE_BORDER is the + old name for this style. + @style{wxBORDER_SUNKEN}: + Displays a sunken border. wxSUNKEN_BORDER is the old name for this + style. + @style{wxBORDER_RAISED}: + Displays a raised border. wxRAISED_BORDER is the old name for this + style. + @style{wxBORDER_STATIC}: + Displays a border suitable for a static control. wxSTATIC_BORDER + is the old name for this style. Windows only. + @style{wxBORDER_THEME}: + Displays a native border suitable for a control, on the current + platform. On Windows XP or Vista, this will be a themed border; on + most other platforms a sunken border will be used. For more + information for themed borders on Windows, please see Themed + borders on Windows. + @style{wxBORDER_NONE}: + Displays no border, overriding the default border style for the + window. wxNO_BORDER is the old name for this style. + @style{wxBORDER_DOUBLE}: + This style is obsolete and should not be used. + @style{wxTRANSPARENT_WINDOW}: + The window is transparent, that is, it will not receive paint + events. Windows only. + @style{wxTAB_TRAVERSAL}: + Use this to enable tab traversal for non-dialog windows. + @style{wxWANTS_CHARS}: + Use this to indicate that the window wants to get all char/key + events for all keys - even for keys like TAB or ENTER which are + usually used for dialog navigation and which wouldn't be generated + without this style. If you need to use this style in order to get + the arrows or etc., but would still like to have normal keyboard + navigation take place, you should call Navigate in response to the + key events for Tab and Shift-Tab. + @style{wxNO_FULL_REPAINT_ON_RESIZE}: + On Windows, this style used to disable repainting the window + completely when its size is changed. Since this behaviour is now + the default, the style is now obsolete and no longer has an effect. + @style{wxVSCROLL}: + Use this style to enable a vertical scrollbar. Notice that this + style cannot be used with native controls which don't support + scrollbars nor with top-level windows in most ports. + @style{wxHSCROLL}: + Use this style to enable a horizontal scrollbar. The same + limitations as for wxVSCROLL apply to this style. + @style{wxALWAYS_SHOW_SB}: + If a window has scrollbars, disable them instead of hiding them + when they are not needed (i.e. when the size of the window is big + enough to not require the scrollbars to navigate it). This style is + currently implemented for wxMSW, wxGTK and wxUniversal and does + nothing on the other platforms. + @style{wxCLIP_CHILDREN}: + Use this style to eliminate flicker caused by the background being + repainted, then children being painted over them. Windows only. + @style{wxFULL_REPAINT_ON_RESIZE}: + Use this style to force a complete redraw of the window whenever it + is resized instead of redrawing just the part of the window + affected by resizing. Note that this was the behaviour by default + before 2.5.1 release and that if you experience redraw problems + with code which previously used to work you may want to try this. + Currently this style applies on GTK+ 2 and Windows only, and full + repainting is always done on other platforms. + @endStyleTable + + @beginExtraStyleTable + @style{wxWS_EX_VALIDATE_RECURSIVELY}: + By default, Validate/TransferDataTo/FromWindow() only work on + direct children of the window (compatible behaviour). Set this flag + to make them recursively descend into all subwindows. + @style{wxWS_EX_BLOCK_EVENTS}: + wxCommandEvents and the objects of the derived classes are + forwarded to the parent window and so on recursively by default. + Using this flag for the given window allows to block this + propagation at this window, i.e. prevent the events from being + propagated further upwards. Dialogs have this flag on by default. + @style{wxWS_EX_TRANSIENT}: + Don't use this window as an implicit parent for the other windows: + this must be used with transient windows as otherwise there is the + risk of creating a dialog/frame with this window as a parent which + would lead to a crash if the parent is destroyed before the child. + @style{wxWS_EX_PROCESS_IDLE}: + This window should always process idle events, even if the mode set + by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. + @style{wxWS_EX_PROCESS_UI_UPDATES}: + This window should always process UI update events, even if the + mode set by wxUpdateUIEvent::SetMode is + wxUPDATE_UI_PROCESS_SPECIFIED. + @endExtraStyleTable + + @library{wxcore} + @category{FIXME} + + @seealso + @ref overview_eventhandlingoverview "Event handling overview", @ref + overview_windowsizingoverview "Window sizing overview" +*/ +class wxWindow : public wxEvtHandler +{ +public: + //@{ + /** + Constructs a window, which can be a child of a frame, dialog or any other + non-control window. + + @param parent + Pointer to a parent window. + + @param id + Window identifier. If wxID_ANY, will automatically create an identifier. + + @param pos + Window position. wxDefaultPosition indicates that wxWidgets + should generate a default position for the window. If using the wxWindow class + directly, supply + an actual position. + + @param size + Window size. wxDefaultSize indicates that wxWidgets + should generate a default size for the window. If no suitable size can be + found, the + window will be sized to 20x20 pixels so that the window is visible but + obviously not + correctly sized. + + @param style + Window style. For generic window styles, please see wxWindow. + + @param name + Window name. + */ + wxWindow(); + wxWindow(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPanelNameStr); + //@} + + /** + Destructor. Deletes all sub-windows, then deletes itself. Instead of using + the @b delete operator explicitly, you should normally + use Destroy() so that wxWidgets + can delete a window only when it is safe to do so, in idle time. + + @sa @ref overview_windowdeletionoverview "Window deletion overview", + Destroy(), wxCloseEvent + */ + ~wxWindow(); + + /** + This method may be overridden in the derived classes to return @false to + indicate that this control doesn't accept input at all (i.e. behaves like e.g. + wxStaticText) and so doesn't need focus. + + @sa AcceptsFocusFromKeyboard() + */ + bool AcceptsFocus(); + + /** + This method may be overridden in the derived classes to return @false to + indicate that while this control can, in principle, have focus if the user + clicks it with the mouse, it shouldn't be included in the TAB traversal chain + when using the keyboard. + */ + bool AcceptsFocusFromKeyboard(); + + /** + Adds a child window. This is called automatically by window creation + functions so should not be required by the application programmer. + + Notice that this function is mostly internal to wxWidgets and shouldn't be + called by the user code. + + @param child + Child window to add. + */ + virtual void AddChild(wxWindow* child); + + /** + Call this function to force one or both scrollbars to be always shown, even if + the window is big enough to show its entire contents without scrolling. + + This function is new since wxWidgets version 2.9.0 + + @param hflag + Whether the horizontal scroll bar should always be visible. + + @param vflag + Whether the vertical scroll bar should always be visible. + + @remarks This function is currently only implemented under Mac/Carbon. + */ + void AlwaysShowScrollbars(bool hflag, bool vflag); + + /** + Sets the cached best size value. + */ + void CacheBestSize(const wxSize& size); + + /** + Returns @true if the system supports transparent windows and calling + SetTransparent() may succeed. If this function + returns @false, transparent windows are definitely not supported by the + current + system. + */ + bool CanSetTransparent(); + + /** + Directs all mouse input to this window. Call ReleaseMouse() to + release the capture. + + Note that wxWidgets maintains the stack of windows having captured the mouse + and when the mouse is released the capture returns to the window which had had + captured it previously and it is only really released if there were no previous + window. In particular, this means that you must release the mouse as many times + as you capture it, unless the window receives + the wxMouseCaptureLostEvent event. + + Any application which captures the mouse in the beginning of some operation + must handle wxMouseCaptureLostEvent + and cancel this operation when it receives the event. The event handler must + not recapture mouse. + + @sa ReleaseMouse(), wxMouseCaptureLostEvent + */ + virtual void CaptureMouse(); + + /** + A synonym for Centre(). + */ + void Center(int direction); + + /** + A synonym for CentreOnParent(). + */ + void CenterOnParent(int direction); + + /** + Centres the window. + + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag + if you want to center the window on the entire screen and not on its + parent window. + + @remarks If the window is a top level one (i.e. doesn't have a parent), + it will be centered relative to the screen anyhow. + + @sa Center() + */ + void Centre(int direction = wxBOTH); + + /** + Centres the window on its parent. This is a more readable synonym for + Centre(). + + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. + + @remarks This methods provides for a way to center top level windows over + their parents instead of the entire screen. If there + is no parent or if the window is not a top level + window, then behaviour is the same as + Centre(). + + @sa wxTopLevelWindow::CentreOnScreen + */ + void CentreOnParent(int direction = wxBOTH); + + /** + Clears the window by filling it with the current background colour. Does not + cause an erase background event to be generated. + */ + void ClearBackground(); + + //@{ + /** + Converts to screen coordinates from coordinates relative to this window. + + + @param x + A pointer to a integer value for the x coordinate. Pass the client coordinate + in, and + a screen coordinate will be passed out. + + @param y + A pointer to a integer value for the y coordinate. Pass the client coordinate + in, and + a screen coordinate will be passed out. + + @param pt + The client position for the second form of the function. + */ + virtual void ClientToScreen(int* x, int* y); + virtual wxPoint ClientToScreen(const wxPoint& pt); + //@} + + /** + Converts client area size @e size to corresponding window size. In other + words, the returned value is what would GetSize() + return if this window had client area of given size. + Components with wxDefaultCoord value are left unchanged. + + Note that the conversion is not always exact, it assumes that non-client area + doesn't change and so doesn't take into account things like menu bar + (un)wrapping or (dis)appearance of the scrollbars. + + @sa WindowToClientSize() + */ + virtual wxSize ClientToWindowSize(const wxSize& size); + + /** + This function simply generates a wxCloseEvent whose + handler usually tries to close the window. It doesn't close the window itself, + however. + + @param force + @false if the window's close handler should be able to veto the destruction + of this window, @true if it cannot. + + @remarks Close calls the close handler for the window, providing an + opportunity for the window to choose whether to + destroy the window. Usually it is only used with the + top level windows (wxFrame and wxDialog classes) as + the others are not supposed to have any special + OnClose() logic. + + @sa @ref overview_windowdeletionoverview "Window deletion overview", + Destroy(), wxCloseEvent + */ + bool Close(bool force = @false); + + //@{ + /** + Converts a point or size from dialog units to pixels. + + For the x dimension, the dialog units are multiplied by the average character + width + and then divided by 4. + + For the y dimension, the dialog units are multiplied by the average character + height + and then divided by 8. + + @remarks Dialog units are used for maintaining a dialog's proportions + even if the font changes. + + @sa ConvertPixelsToDialog() + */ + wxPoint ConvertDialogToPixels(const wxPoint& pt); + wxSize ConvertDialogToPixels(const wxSize& sz); + //@} + + //@{ + /** + Converts a point or size from pixels to dialog units. + + For the x dimension, the pixels are multiplied by 4 and then divided by the + average + character width. + + For the y dimension, the pixels are multiplied by 8 and then divided by the + average + character height. + + @remarks Dialog units are used for maintaining a dialog's proportions + even if the font changes. + + @sa ConvertDialogToPixels() + */ + wxPoint ConvertPixelsToDialog(const wxPoint& pt); + wxSize ConvertPixelsToDialog(const wxSize& sz); + //@} + + /** + Destroys the window safely. Use this function instead of the delete operator, + since + different window classes can be destroyed differently. Frames and dialogs + are not destroyed immediately when this function is called -- they are added + to a list of windows to be deleted on idle time, when all the window's events + have been processed. This prevents problems with events being sent to + non-existent + windows. + + @returns @true if the window has either been successfully deleted, or it + has been added to the list of windows pending real + deletion. + */ + virtual bool Destroy(); + + /** + Destroys all children of a window. Called automatically by the destructor. + */ + virtual void DestroyChildren(); + + /** + Disables the window, same as @ref enable() Enable(@false). + + @returns Returns @true if the window has been disabled, @false if it had + been already disabled before the call to this + function. + */ + bool Disable(); + + /** + Gets the size which best suits the window: for a control, it would be + the minimal size which doesn't truncate the control, for a panel - the + same size as it would have after a call to Fit(). + */ + virtual wxSize DoGetBestSize(); + + /** + Does the window-specific updating after processing the update event. + This function is called by UpdateWindowUI() + in order to check return values in the wxUpdateUIEvent and + act appropriately. For example, to allow frame and dialog title updating, + wxWidgets + implements this function as follows: + */ + virtual void DoUpdateWindowUI(wxUpdateUIEvent& event); + + /** + Enables or disables eligibility for drop file events (OnDropFiles). + + @param accept + If @true, the window is eligible for drop file events. If @false, the window + will not accept drop file events. + + @remarks Windows only. + */ + virtual void DragAcceptFiles(bool accept); + + /** + Enable or disable the window for user input. Note that when a parent window is + disabled, all of its children are disabled as well and they are reenabled again + when the parent is. + + @param enable + If @true, enables the window for input. If @false, disables the window. + + @returns Returns @true if the window has been enabled or disabled, @false + if nothing was done, i.e. if the window had already + been in the specified state. + + @sa IsEnabled(), Disable(), wxRadioBox::Enable + */ + virtual bool Enable(bool enable = @true); + + /** + Finds the window or control which currently has the keyboard focus. + + @remarks Note that this is a static function, so it can be called without + needing a wxWindow pointer. + + @sa SetFocus(), HasFocus() + */ + static wxWindow* FindFocus(); + + //@{ + /** + Find a child of this window, by name. + */ + wxWindow* FindWindow(long id); + wxWindow* FindWindow(const wxString& name); + //@} + + /** + Find the first window with the given @e id. + + If @e parent is @NULL, the search will start from all top-level + frames and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + + @sa FindWindow() + */ + static wxWindow* FindWindowById(long id, wxWindow* parent = @NULL); + + /** + Find a window by its label. Depending on the type of window, the label may be a + window title + or panel item label. If @e parent is @NULL, the search will start from all + top-level + frames and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + + @sa FindWindow() + */ + static wxWindow* FindWindowByLabel(const wxString& label, + wxWindow* parent = @NULL); + + /** + Find a window by its name (as given in a window constructor or @b Create + function call). + If @e parent is @NULL, the search will start from all top-level + frames and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + + If no window with such name is found, + FindWindowByLabel() is called. + + @sa FindWindow() + */ + static wxWindow* FindWindowByName(const wxString& name, + wxWindow* parent = @NULL); + + /** + Sizes the window so that it fits around its subwindows. This function won't do + anything if there are no subwindows and will only really work correctly if + sizers are used for the subwindows layout. Also, if the window has exactly one + subwindow it is better (faster and the result is more precise as Fit adds some + margin to account for fuzziness of its calculations) to call + instead of calling Fit. + */ +#define virtual void Fit() /* implementation is private */ + + /** + Similar to Fit(), but sizes the interior (virtual) size + of a window. Mainly useful with scrolled windows to reset scrollbars after + sizing changes that do not trigger a size event, and/or scrolled windows without + an interior sizer. This function similarly won't do anything if there are no + subwindows. + */ + virtual void FitInside(); + + /** + Freezes the window or, in other words, prevents any updates from taking place + on screen, the window is not redrawn at all. Thaw() must + be called to reenable window redrawing. Calls to these two functions may be + nested but to ensure that the window is properly repainted again, you must thaw + it exactly as many times as you froze it. + + This method is useful for visual appearance optimization (for example, it + is a good idea to use it before doing many large text insertions in a row into + a wxTextCtrl under wxGTK) but is not implemented on all platforms nor for all + controls so it is mostly just a hint to wxWidgets and not a mandatory + directive. + + @sa wxWindowUpdateLocker + */ + virtual void Freeze(); + + /** + Gets the accelerator table for this window. See wxAcceleratorTable. + */ + wxAcceleratorTable* GetAcceleratorTable(); + + /** + Returns the accessible object for this window, if any. + + See also wxAccessible. + */ + wxAccessible* GetAccessible(); + + /** + This method is deprecated, use GetEffectiveMinSize() + instead. + */ + wxSize GetAdjustedBestSize(); + + /** + Returns the background colour of the window. + + @sa SetBackgroundColour(), SetForegroundColour(), + GetForegroundColour() + */ + virtual wxColour GetBackgroundColour(); + + /** + Returns the background style of the window. The background style can be one of: + + + wxBG_STYLE_SYSTEM + + + Use the default background, as determined by + the system or the current theme. + + wxBG_STYLE_COLOUR + + + Use a solid colour for the background, this + style is set automatically if you call + SetBackgroundColour() so you only need to + set it explicitly if you had changed the background style to something else + before. + + wxBG_STYLE_CUSTOM + + + Don't draw the background at all, it's + supposed that it is drawn by the user-defined erase background event handler. + This style should be used to avoid flicker when the background is entirely + custom-drawn. + + wxBG_STYLE_TRANSPARET + + + The background is (partially) transparent, + this style is automatically set if you call + SetTransparent() which is used to set the + transparency level. + + + @sa SetBackgroundColour(), GetForegroundColour(), + SetBackgroundStyle(), SetTransparent() + */ + virtual wxBackgroundStyle GetBackgroundStyle(); + + /** + This functions returns the best acceptable minimal size for the window. For + example, for a static control, it will be the minimal size such that the + control label is not truncated. For windows containing subwindows (typically + wxPanel), the size returned by this function will be the + same as the size the window would have had after calling + Fit(). + */ + wxSize GetBestSize(); + + /** + Returns the currently captured window. + + @sa HasCapture(), CaptureMouse(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + */ + static wxWindow * GetCapture(); + + /** + Returns the caret associated with the window. + */ + wxCaret * GetCaret(); + + /** + Returns the character height for this window. + */ + virtual int GetCharHeight(); + + /** + Returns the average character width for this window. + */ + virtual int GetCharWidth(); + + //@{ + /** + Returns a reference to the list of the window's children. @c wxWindowList + is a type-safe wxList-like class whose elements are of type + @c wxWindow *. + */ + wxWindowList GetChildren(); + const wxWindowList GetChildren(); + //@} + + /** + Returns the default font and colours which are used by the control. This is + useful if you want to use the same font or colour in your own control as in a + standard control -- which is a much better idea than hard coding specific + colours or fonts which might look completely out of place on the users + system, especially if it uses themes. + + The @e variant parameter is only relevant under Mac currently and is + ignore under other platforms. Under Mac, it will change the size of the + returned font. See SetWindowVariant() + for more about this. + + This static method is "overridden'' in many derived classes and so calling, + for example, wxButton::GetClassDefaultAttributes() will typically + return the values appropriate for a button which will be normally different + from those returned by, say, wxListCtrl::GetClassDefaultAttributes(). + + The @c wxVisualAttributes structure has at least the fields + @c font, @c colFg and @c colBg. All of them may be invalid + if it was not possible to determine the default control appearance or, + especially for the background colour, if the field doesn't make sense as is + the case for @c colBg for the controls with themed background. + + @sa InheritAttributes() + */ + static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); + + //@{ + /** + Returns the size of the window 'client area' in pixels. The client area is the + area which may be drawn on by the programmer, excluding title bar, border, + scrollbars, etc. + + Note that if this window is a top-level one and it is currently minimized, the + return size is empty (both width and height are 0). + + @param width + Receives the client width in pixels. + + @param height + Receives the client height in pixels. + + @sa GetSize(), GetVirtualSize() + */ + void GetClientSize(int* width, int* height); + wxSize GetClientSize(); + //@} + + /** + Returns a pointer to the window's layout constraints, or @NULL if there are none. + */ + wxLayoutConstraints* GetConstraints(); + + /** + Return the sizer that this window is a member of, if any, otherwise + @NULL. + */ + const wxSizer * GetContainingSizer(); + + /** + Return the cursor associated with this window. + + @sa SetCursor() + */ + const wxCursor GetCursor(); + + /** + Currently this is the same as calling + wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()). + + One advantage of using this function compared to the static version is that + the call is automatically dispatched to the correct class (as usual with + virtual functions) and you don't have to specify the class name explicitly. + + The other one is that in the future this function could return different + results, for example it might return a different font for an "Ok'' button + than for a generic button if the users GUI is configured to show such buttons + in bold font. Of course, the down side is that it is impossible to call this + function without actually having an object to apply it to whereas the static + version can be used without having to create an object first. + */ + virtual wxVisualAttributes GetDefaultAttributes(); + + /** + Returns the associated drop target, which may be @NULL. + + @sa SetDropTarget(), @ref overview_wxdndoverview "Drag and drop + overview" + */ + wxDropTarget* GetDropTarget(); + + /** + Merges the window's best size into the min size and returns the + result. This is the value used by sizers to determine the appropriate + ammount of space to allocate for the widget. + + @sa GetBestSize(), SetInitialSize() + */ + wxSize GetEffectiveMinSize(); + + /** + Returns the event handler for this window. By default, the window is its + own event handler. + + @sa SetEventHandler(), PushEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + wxEvtHandler* GetEventHandler(); + + /** + Returns the extra style bits for the window. + */ + long GetExtraStyle(); + + /** + Returns the font for this window. + + @sa SetFont() + */ + wxFont GetFont(); + + /** + Returns the foreground colour of the window. + + @remarks The interpretation of foreground colour is open to + interpretation according to the window class; it may + be the text colour or other colour, or it may not be + used at all. + + @sa SetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour() + */ + virtual wxColour GetForegroundColour(); + + /** + Returns the grandparent of a window, or @NULL if there isn't one. + */ + wxWindow* GetGrandParent(); + + /** + Returns the platform-specific handle of the physical window. Cast it to an + appropriate + handle, such as @b HWND for Windows, @b Widget for Motif, @b GtkWidget for GTK + or @b WinHandle for PalmOS. + */ + void* GetHandle(); + + /** + Gets the help text to be used as context-sensitive help for this window. + + Note that the text is actually stored by the current wxHelpProvider + implementation, + and not in the window object itself. + + @sa SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider + */ + virtual wxString GetHelpText(); + + /** + Gets the help text to be used as context-sensitive help for this window. This + method should be overridden if the help message depends on the position inside + the window, otherwise GetHelpText() can be used. + + @param point + Coordinates of the mouse at the moment of help event emission. + + @param origin + Help event origin, see also wxHelpEvent::GetOrigin. + */ + virtual wxString GetHelpTextAtPoint(const wxPoint point, + wxHelpEvent::Origin origin); + + /** + Returns the identifier of the window. + + @remarks Each window has an integer identifier. If the application has + not provided one (or the default wxID_ANY) an unique + identifier with a negative value will be generated. + + @sa SetId(), @ref overview_windowids "Window identifiers" + */ + int GetId(); + + /** + Generic way of getting a label from any window, for + identification purposes. + + @remarks The interpretation of this function differs from class to class. + For frames and dialogs, the value returned is the + title. For buttons or static text controls, it is the + button text. This function can be useful for + meta-programs (such as testing tools or special-needs + access programs) which need to identify windows by + name. + */ + virtual wxString GetLabel(); + + /** + Returns the maximum size of window's client area. + This is an indication to the sizer layout mechanism that this is the maximum + possible size as well as the upper bound on window's size settable using + SetClientSize(). + + @sa GetMaxSize() + */ + wxSize GetMaxClientSize(); + + /** + Returns the maximum size of the window. This is an indication to the sizer + layout mechanism that this is the maximum possible size as well as the upper + bound on window's size settable using SetSize(). + + @sa GetMaxClientSize() + */ + wxSize GetMaxSize(); + + /** + Returns the minimum size of window's client area, an indication to the sizer + layout mechanism that this is the minimum required size of its client area. It + normally just returns the value set by + SetMinClientSize(), but it can be overridden + to do the calculation on demand. + + @sa GetMinSize() + */ + virtual wxSize GetMinClientSize(); + + /** + Returns the minimum size of the window, an indication to the sizer layout + mechanism + that this is the minimum required size. It normally just returns the value set + by SetMinSize(), but it can be overridden to do the + calculation on demand. + + @sa GetMinClientSize() + */ + virtual wxSize GetMinSize(); + + /** + Returns the window's name. + + @remarks This name is not guaranteed to be unique; it is up to the + programmer to supply an appropriate name in the + window constructor or via SetName(). + + @sa SetName() + */ + virtual wxString GetName(); + + /** + Returns the next window after this one among the parent children or @NULL if + this window is the last child. + + This function is new since wxWidgets version 2.8.8 + + @sa GetPrevSibling() + */ + wxWindow * GetNextSibling(); + + /** + Returns the parent of the window, or @NULL if there is no parent. + */ + virtual wxWindow* GetParent(); + + //@{ + /** + This function shows a popup menu at the given position in this window and + returns the selected id. It can be more convenient than the general purpose + PopupMenu() function for simple menus proposing a + choice in a list of strings to the user. + + @param menu + The menu to show + + @param pos + The position at which to show the menu in client coordinates + + @param x + The horizontal position of the menu + + @param y + The vertical position of the menu + + @returns The selected menu item id or wxID_NONE if none selected or an + error occurred. + */ + int GetPopupMenuSelectionFromUser(wxMenu& menu, + const wxPoint& pos); + int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); + //@} + + //@{ + /** + This gets the position of the window in pixels, relative to the parent window + for the child windows or relative to the display origin for the top level + windows. + + @param x + Receives the x position of the window if non-@NULL. + + @param y + Receives the y position of the window if non-@NULL. + + @sa GetScreenPosition() + */ + virtual void GetPosition(int* x, int* y); + wxPoint GetPosition(); + //@} + + /** + Returns the previous window before this one among the parent children or @c + @NULL if + this window is the first child. + + This function is new since wxWidgets version 2.8.8 + + @sa GetNextSibling() + */ + wxWindow * GetPrevSibling(); + + /** + Returns the position and size of the window as a wxRect object. + + @sa GetScreenRect() + */ + virtual wxRect GetRect(); + + //@{ + /** + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. + + @param x + Receives the x position of the window on the screen if non-@NULL. + + @param y + Receives the y position of the window on the screen if non-@NULL. + + @sa GetPosition() + */ + virtual void GetScreenPosition(int* x, int* y); + wxPoint GetScreenPosition(); + //@} + + /** + Returns the position and size of the window on the screen as a + wxRect object. + + @sa GetRect() + */ + virtual wxRect GetScreenRect(); + + /** + Returns the built-in scrollbar position. + + @sa See SetScrollbar() + */ + virtual int GetScrollPos(int orientation); + + /** + Returns the built-in scrollbar range. + + @sa SetScrollbar() + */ + virtual int GetScrollRange(int orientation); + + /** + Returns the built-in scrollbar thumb size. + + @sa SetScrollbar() + */ + virtual int GetScrollThumb(int orientation); + + //@{ + /** + Returns the size of the entire window in pixels, including title bar, border, + scrollbars, etc. + + Note that if this window is a top-level one and it is currently minimized, the + returned size is the restored window size, not the size of the window icon. + + @param width + Receives the window width. + + @param height + Receives the window height. + + @sa GetClientSize(), GetVirtualSize() + */ + void GetSize(int* width, int* height); + wxSize GetSize(); + //@} + + /** + Return the sizer associated with the window by a previous call to + SetSizer() or @NULL. + */ + wxSizer * GetSizer(); + + //@{ + /** + Gets the dimensions of the string as it would be drawn on the + window with the currently selected font. + + The text extent is returned in @e w and @e h pointers (first form) or as a + wxSize object (second form). + + @param string + String whose extent is to be measured. + + @param w + Return value for width. + + @param h + Return value for height. + + @param descent + Return value for descent (optional). + + @param externalLeading + Return value for external leading (optional). + + @param font + Font to use instead of the current window font (optional). + + @param use16 + If @true, string contains 16-bit characters. The default is @false. + */ + virtual void GetTextExtent(const wxString& string, int* w, + int* h, + int* descent = @NULL, + int* externalLeading = @NULL, + const wxFont* font = @NULL, + bool use16 = @false); + wxSize GetTextExtent(const wxString& string); + //@} + + /** + Get the associated tooltip or @NULL if none. + */ + wxToolTip* GetToolTip(); + + /** + Returns the region specifying which parts of the window have been damaged. + Should + only be called within an wxPaintEvent handler. + + @sa wxRegion, wxRegionIterator + */ + virtual wxRegion GetUpdateRegion(); + + /** + Returns a pointer to the current validator for the window, or @NULL if there is + none. + */ + wxValidator* GetValidator(); + + //@{ + /** + This gets the virtual size of the window in pixels. By default it + returns the client size of the window, but after a call to + SetVirtualSize() it will return + that size. + + @param width + Receives the window virtual width. + + @param height + Receives the window virtual height. + */ + void GetVirtualSize(int* width, int* height); + wxSize GetVirtualSize(); + //@} + + /** + Returns the size of the left/right and top/bottom borders of this window in x + and y components of the result respectively. + */ + wxSize GetWindowBorderSize(); + + /** + Gets the window style that was passed to the constructor or @b Create + method. @b GetWindowStyle() is another name for the same function. + */ + long GetWindowStyleFlag(); + + /** + Returns the value previously passed to + SetWindowVariant(). + */ + wxWindowVariant GetWindowVariant(); + + /** + This function will generate the appropriate call to + Navigate() if the key event is one normally used for + keyboard navigation and return @true in this case. + + @returns Returns @true if the key pressed was for navigation and was + handled, @false otherwise. + + @sa Navigate() + */ + bool HandleAsNavigationKey(const wxKeyEvent& event); + + /** + Shorthand for @c + wxWindow::GetEventHandler()-wxEvtHandler::SafelyProcessEvent(event). + */ + bool HandleWindowEvent(wxEvent& event); + + /** + Returns @true if this window has the current mouse capture. + + @sa CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, + wxMouseCaptureChangedEvent + */ + virtual bool HasCapture(); + + /** + Returns @true if the window has the given @e exFlag bit set in its + extra styles. + + @sa SetExtraStyle() + */ + bool HasExtraStyle(int exFlag); + + /** + Returns @true if the window has the given @e flag bit set. + */ + bool HasFlag(int flag); + + /** + Returns @true if the window (or in case of composite controls, its main + child window) has focus. + + @sa FindFocus() + */ + virtual bool HasFocus(); + + /** + This method should be overridden to return @true if this window has + multiple pages. All standard class with multiple pages such as + wxNotebook, wxListbook and + wxTreebook already override it to return @true + and user-defined classes with similar behaviour should do it as well to allow + the library to handle such windows appropriately. + */ + virtual bool HasMultiplePages(); + + /** + Returns @true if this window has a scroll bar for this orientation. + + @param orient + Orientation to check, either wxHORIZONTAL or wxVERTICAL. + */ + virtual bool HasScrollbar(int orient); + + /** + Returns @true if this window background is transparent (as, for example, for + wxStaticText) and should show the parent window background. + + This method is mostly used internally by the library itself and you normally + shouldn't have to call it. You may, however, have to override it in your + wxWindow-derived class to ensure that background is painted correctly. + */ + virtual bool HasTransparentBackground(); + + /** + Equivalent to calling wxWindow::Show(@false). + */ + bool Hide(); + + /** + This function hides a window, like Hide(), but using a + special visual effect if possible. + + The parameters of this function are the same as for + ShowWithEffect(), please see their + description there. + + This function is new since wxWidgets version 2.9.0 + */ + virtual bool HideWithEffect(wxShowEffect effect, + unsigned timeout = 0, + wxDirection dir = wxBOTTOM); + + /** + This function is (or should be, in case of custom controls) called during + window creation to intelligently set up the window visual attributes, that is + the font and the foreground and background colours. + + By "intelligently'' the following is meant: by default, all windows use their + own @ref getclassdefaultattributes() default attributes. However + if some of the parents attributes are explicitly (that is, using + SetFont() and not + wxWindow::SetOwnFont) changed and if the + corresponding attribute hadn't been explicitly set for this window itself, + then this window takes the same value as used by the parent. In addition, if + the window overrides ShouldInheritColours() + to return @false, the colours will not be changed no matter what and only the + font might. + + This rather complicated logic is necessary in order to accommodate the + different usage scenarios. The most common one is when all default attributes + are used and in this case, nothing should be inherited as in modern GUIs + different controls use different fonts (and colours) than their siblings so + they can't inherit the same value from the parent. However it was also deemed + desirable to allow to simply change the attributes of all children at once by + just changing the font or colour of their common parent, hence in this case we + do inherit the parents attributes. + */ + void InheritAttributes(); + + /** + Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data + to the dialog via validators. + */ + void InitDialog(); + + /** + Resets the cached best size value so it will be recalculated the next time it + is needed. + */ + void InvalidateBestSize(); + + /** + Returns @true if the window contents is double-buffered by the system, i.e. if + any drawing done on the window is really done on a temporary backing surface + and transferred to the screen all at once later. + + @sa wxBufferedDC + */ + virtual bool IsDoubleBuffered(); + + /** + Returns @true if the window is enabled, i.e. if it accepts user input, @c + @false + otherwise. + + Notice that this method can return @false even if this window itself hadn't + been explicitly disabled when one of its parent windows is disabled. To get the + intrinsic status of this window, use + IsThisEnabled() + + @sa Enable() + */ + virtual bool IsEnabled(); + + //@{ + /** + Returns @true if the given point or rectangle area has been exposed since the + last repaint. Call this in an paint event handler to optimize redrawing by + only redrawing those areas, which have been exposed. + */ + bool IsExposed(int x, int y); + bool IsExposed(wxPoint amp;pt); + bool IsExposed(int x, int y, int w, int h); + bool IsExposed(wxRect amp;rect); + //@} + + /** + Returns @true if the window is currently frozen by a call to + Freeze(). + + @sa Thaw() + */ + virtual bool IsFrozen(); + + /** + Returns @true if the window is retained, @false otherwise. + + @remarks Retained windows are only available on X platforms. + */ + virtual bool IsRetained(); + + /** + Return whether a scrollbar is always shown. + + @param orient + Orientation to check, either wxHORIZONTAL or wxVERTICAL. + + @sa AlwaysShowScrollbars() + */ + bool IsScrollbarAlwaysShown(int orient); + + /** + Returns @true if the window is shown, @false if it has been hidden. + + @sa IsShownOnScreen() + */ + virtual bool IsShown(); + + /** + Returns @true if the window is physically visible on the screen, i.e. it + is shown and all its parents up to the toplevel window are shown as well. + + @sa IsShown() + */ + virtual bool IsShownOnScreen(); + + /** + Returns @true if this window is intrinsically enabled, @false otherwise, + i.e. + if @ref enable() Enable(@false) had been called. This method is + mostly used for wxWidgets itself, user code should normally use + IsEnabled() instead. + */ + bool IsThisEnabled(); + + /** + Returns @true if the given window is a top-level one. Currently all frames and + dialogs are considered to be top-level windows (even if they have a parent + window). + */ + bool IsTopLevel(); + + /** + Invokes the constraint-based layout algorithm or the sizer-based algorithm + for this window. + + See SetAutoLayout(): when auto + layout is on, this function gets called automatically when the window is + resized. + */ + void Layout(); + + /** + This is just a wrapper for wxWindow::ScrollLines(1). + */ + + + /** + This is just a wrapper for wxWindow::ScrollLines(-1). + */ + + + /** + Lowers the window to the bottom of the window hierarchy (Z-order). + + @sa Raise() + */ + void Lower(); + + /** + Disables all other windows in the application so that + the user can only interact with this window. + + @param flag + If @true, this call disables all other windows in the application so that + the user can only interact with this window. If @false, the effect is reversed. + */ + virtual void MakeModal(bool flag); + + //@{ + /** + Moves the window to the given position. + + @param x + Required x position. + + @param y + Required y position. + + @param pt + wxPoint object representing the position. + + @remarks Implementations of SetSize can also implicitly implement the + Move() function, which is defined in the base + wxWindow class as the call: + + @sa SetSize() + */ + void Move(int x, int y); + void Move(const wxPoint& pt); + //@} + + /** + Moves this window in the tab navigation order after the specified @e win. + This means that when the user presses @c TAB key on that other window, + the focus switches to this window. + + Default tab order is the same as creation order, this function and + MoveBeforeInTabOrder() allow to change + it after creating all the windows. + + @param win + A sibling of this window which should precede it in tab order, + must not be @NULL + */ + void MoveAfterInTabOrder(wxWindow * win); + + /** + Same as MoveAfterInTabOrder() except that + it inserts this window just before @e win instead of putting it right after + it. + */ + void MoveBeforeInTabOrder(wxWindow * win); + + /** + Performs a keyboard navigation action starting from this window. This method is + equivalent to calling NavigateIn() method on the + parent window. + + @param flags + A combination of wxNavigationKeyEvent::IsForward and + wxNavigationKeyEvent::WinChange. + + @returns Returns @true if the focus was moved to another window or @false + if nothing changed. + + @remarks You may wish to call this from a text control custom keypress + handler to do the default navigation behaviour for + the tab key, since the standard default behaviour for + a multiline text control with the wxTE_PROCESS_TAB + style is to insert a tab and not navigate to the next + control. See also wxNavigationKeyEvent and + HandleAsNavigationKey. + */ + bool Navigate(int flags = wxNavigationKeyEvent::IsForward); + + /** + Performs a keyboard navigation action inside this window. + + See Navigate() for more information. + */ + bool NavigateIn(int flags = wxNavigationKeyEvent::IsForward); + + /** + Create a new ID or range of IDs that are not currently in use. The + IDs will be reserved until assigned to a wxWindowIDRef + or unreserved with UnreserveControlId(). + + See @ref overview_windowidsoverview "Window IDs overview" for more information. + + @param count + The number of sequential IDs to reserve. + + @returns Returns the ID or the first ID of the range, or wxID_NONE if the + specified number of identifiers couldn't be allocated. + + @sa UnreserveControlId(), wxIdManager, @ref overview_windowidsoverview + "Window IDs overview" + */ + static wxWindowID NewControlId(int count = 1); + + /** + This virtual function is normally only used internally, but + sometimes an application may need it to implement functionality + that should not be disabled by an application defining an OnIdle + handler in a derived class. + + This function may be used to do delayed painting, for example, + and most implementations call UpdateWindowUI() + in order to send update events to the window in idle time. + */ + virtual void OnInternalIdle(); + + /** + This is just a wrapper for wxWindow::ScrollPages(1). + */ + + + /** + This is just a wrapper for wxWindow::ScrollPages(-1). + */ + + + /** + Removes and returns the top-most event handler on the event handler stack. + + @param deleteHandler + If this is @true, the handler will be deleted after it is removed. The + default value is @false. + + @sa SetEventHandler(), GetEventHandler(), + PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + wxEvtHandler* PopEventHandler(bool deleteHandler = @false); + + //@{ + /** + Pops up the given menu at the specified coordinates, relative to this + window, and returns control when the user has dismissed the menu. If a + menu item is selected, the corresponding menu event is generated and will be + processed as usually. If the coordinates are not specified, current mouse + cursor position is used. + + @param menu + Menu to pop up. + + @param pos + The position where the menu will appear. + + @param x + Required x position for the menu to appear. + + @param y + Required y position for the menu to appear. + + @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to + ensure that the menu items are in the correct state. + The menu does not get deleted by the window. + + @sa wxMenu + */ + bool PopupMenu(wxMenu* menu, + const wxPoint& pos = wxDefaultPosition); + bool PopupMenu(wxMenu* menu, int x, int y); + //@} + + /** + Pushes this event handler onto the event stack for the window. + + @param handler + Specifies the handler to be pushed. + + @remarks An event handler is an object that is capable of processing the + events sent to a window. By default, the window is + its own event handler, but an application may wish to + substitute another, for example to allow central + implementation of event-handling for a variety of + different window classes. + + @sa SetEventHandler(), GetEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + void PushEventHandler(wxEvtHandler* handler); + + /** + Raises the window to the top of the window hierarchy (Z-order). + + In current version of wxWidgets this works both for managed and child windows. + + @sa Lower() + */ + void Raise(); + + /** + Causes this window, and all of its children recursively (except under wxGTK1 + where this is not implemented), to be repainted. Note that repainting doesn't + happen immediately but only during the next event loop iteration, if you need + to update the window immediately you should use Update() + instead. + + @param eraseBackground + If @true, the background will be + erased. + + @param rect + If non-@NULL, only the given rectangle will + be treated as damaged. + + @sa RefreshRect() + */ + virtual void Refresh(bool eraseBackground = @true, + const wxRect* rect = @NULL); + + /** + Redraws the contents of the given rectangle: only the area inside it will be + repainted. + + This is the same as Refresh() but has a nicer syntax + as it can be called with a temporary wxRect object as argument like this + @c RefreshRect(wxRect(x, y, w, h)). + */ + void RefreshRect(const wxRect& rect, bool eraseBackground = @true); + + /** + Registers a system wide hotkey. Every time the user presses the hotkey + registered here, this window + will receive a hotkey event. It will receive the event even if the application + is in the background + and does not have the input focus because the user is working with some other + application. + + @param hotkeyId + Numeric identifier of the hotkey. For applications this must be between 0 and + 0xBFFF. If + this function is called from a shared DLL, it must be a system wide unique + identifier between 0xC000 and 0xFFFF. + This is a MSW specific detail. + + @param modifiers + A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT + or wxMOD_WIN specifying the modifier keys that have to be pressed along with + the key. + + @param virtualKeyCode + The virtual key code of the hotkey. + + @returns @true if the hotkey was registered successfully. @false if some + other application already registered a hotkey with + this modifier/virtualKeyCode combination. + + @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the + event. This function is currently only implemented + under Windows. It is used in the Windows CE port for + detecting hardware button presses. + + @sa UnregisterHotKey() + */ + bool RegisterHotKey(int hotkeyId, int modifiers, + int virtualKeyCode); + + /** + Releases mouse input captured with CaptureMouse(). + + @sa CaptureMouse(), HasCapture(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + */ + virtual void ReleaseMouse(); + + /** + Removes a child window. This is called automatically by window deletion + functions so should not be required by the application programmer. + + Notice that this function is mostly internal to wxWidgets and shouldn't be + called by the user code. + + @param child + Child window to remove. + */ + virtual void RemoveChild(wxWindow* child); + + /** + Find the given @e handler in the windows event handler chain and remove (but + not delete) it from it. + + @param handler + The event handler to remove, must be non-@NULL and + must be present in this windows event handlers chain + + @returns Returns @true if it was found and @false otherwise (this also + results in an assert failure so this function should + only be called when the handler is supposed to be + there). + + @sa PushEventHandler(), PopEventHandler() + */ + bool RemoveEventHandler(wxEvtHandler * handler); + + /** + Reparents the window, i.e the window will be removed from its + current parent window (e.g. a non-standard toolbar in a wxFrame) + and then re-inserted into another. + + @param newParent + New parent. + */ + virtual bool Reparent(wxWindow* newParent); + + //@{ + /** + Converts from screen to client window coordinates. + + @param x + Stores the screen x coordinate and receives the client x coordinate. + + @param y + Stores the screen x coordinate and receives the client x coordinate. + + @param pt + The screen position for the second form of the function. + */ + virtual void ScreenToClient(int* x, int* y); + virtual wxPoint ScreenToClient(const wxPoint& pt); + //@} + + /** + Scrolls the window by the given number of lines down (if @e lines is + positive) or up. + + @returns Returns @true if the window was scrolled, @false if it was already + on top/bottom and nothing was done. + + @remarks This function is currently only implemented under MSW and + wxTextCtrl under wxGTK (it also works for + wxScrolledWindow derived classes under all platforms). + + @sa ScrollPages() + */ + virtual bool ScrollLines(int lines); + + /** + Scrolls the window by the given number of pages down (if @e pages is + positive) or up. + + @returns Returns @true if the window was scrolled, @false if it was already + on top/bottom and nothing was done. + + @remarks This function is currently only implemented under MSW and wxGTK. + + @sa ScrollLines() + */ + virtual bool ScrollPages(int pages); + + /** + Physically scrolls the pixels in the window and move child windows accordingly. + + @param dx + Amount to scroll horizontally. + + @param dy + Amount to scroll vertically. + + @param rect + Rectangle to scroll, if it is @NULL, the whole window is + scrolled (this is always the case under wxGTK which doesn't support this + parameter) + + @remarks Note that you can often use wxScrolledWindow instead of using + this function directly. + */ + virtual void ScrollWindow(int dx, int dy, + const wxRect* rect = @NULL); + + /** + Sets the accelerator table for this window. See wxAcceleratorTable. + */ + virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); + + /** + Sets the accessible for this window. Any existing accessible for this window + will be deleted first, if not identical to @e accessible. + + See also wxAccessible. + */ + void SetAccessible(wxAccessible* accessible); + + /** + Determines whether the Layout() function will + be called automatically when the window is resized. Please note that this only + happens for the windows usually used to contain children, namely + wxPanel and wxTopLevelWindow + (and the classes deriving from them). + + This method is called implicitly by + SetSizer() but if you use + SetConstraints() you should call it + manually or otherwise the window layout won't be correctly updated when its + size changes. + + @param autoLayout + Set this to @true if you wish the Layout function to be + called automatically when the window is resized. + + @sa SetConstraints() + */ + void SetAutoLayout(bool autoLayout); + + /** + Sets the background colour of the window. + + Please see InheritAttributes() for + explanation of the difference between this method and + SetOwnBackgroundColour(). + + @param colour + The colour to be used as the background colour, pass + wxNullColour to reset to the default colour. + + @remarks The background colour is usually painted by the default + wxEraseEvent event handler function under Windows and + automatically under GTK. + + @sa GetBackgroundColour(), SetForegroundColour(), + GetForegroundColour(), ClearBackground(), + Refresh(), wxEraseEvent + */ + virtual bool SetBackgroundColour(const wxColour& colour); + + /** + Sets the background style of the window. see + GetBackgroundStyle() for the description + of the possible style values. + + @sa SetBackgroundColour(), GetForegroundColour(), + SetTransparent() + */ + virtual void SetBackgroundStyle(wxBackgroundStyle style); + + /** + This method is only implemented by ports which have support for + native TAB traversal (such as GTK+ 2.0). It is called by wxWidgets' + container control code to give the native system a hint when + doing TAB traversal. A call to this does not disable or change + the effect of programmatically calling + SetFocus(). + + @sa wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren + */ + virtual void SetCanFocus(bool canFocus); + + /** + Sets the caret associated with the window. + */ + void SetCaret(wxCaret * caret); + + //@{ + /** + This sets the size of the window client area in pixels. Using this function to + size a window + tends to be more device-independent than SetSize(), since the application need + not + worry about what dimensions the border or title bar have when trying to fit the + window + around panel items, for example. + + @param width + The required client area width. + + @param height + The required client area height. + + @param size + The required client size. + */ + virtual void SetClientSize(int width, int height); + virtual void SetClientSize(const wxSize& size); + //@} + + /** + Sets the window to have the given layout constraints. The window + will then own the object, and will take care of its deletion. + If an existing layout constraints object is already owned by the + window, it will be deleted. + + @param constraints + The constraints to set. Pass @NULL to disassociate and delete the window's + constraints. + + @remarks You must call SetAutoLayout() to tell a window to use + the constraints automatically in OnSize; otherwise, + you must override OnSize and call Layout() + explicitly. When setting both a wxLayoutConstraints + and a wxSizer, only the sizer will have effect. + */ + void SetConstraints(wxLayoutConstraints* constraints); + + /** + This normally does not need to be called by user code. It is called + when a window is added to a sizer, and is used so the window can + remove itself from the sizer when it is destroyed. + */ + void SetContainingSizer(wxSizer* sizer); + + /** + Sets the window's cursor. Notice that the window cursor also sets it for the + children of the window implicitly. + + The @e cursor may be @c wxNullCursor in which case the window cursor will + be reset back to default. + + @param cursor + Specifies the cursor that the window should normally display. + + @sa ::wxSetCursor, wxCursor + */ + virtual void SetCursor(const wxCursor& cursor); + + /** + Associates a drop target with this window. + + If the window already has a drop target, it is deleted. + + @sa GetDropTarget(), @ref overview_wxdndoverview "Drag and drop + overview" + */ + void SetDropTarget(wxDropTarget* target); + + /** + Sets the event handler for this window. + + @param handler + Specifies the handler to be set. + + @remarks An event handler is an object that is capable of processing the + events sent to a window. By default, the window is + its own event handler, but an application may wish to + substitute another, for example to allow central + implementation of event-handling for a variety of + different window classes. + + @sa GetEventHandler(), PushEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + void SetEventHandler(wxEvtHandler* handler); + + /** + Sets the extra style bits for the window. The currently defined extra style + bits are: + + @b wxWS_EX_VALIDATE_RECURSIVELY + + + TransferDataTo/FromWindow() + and Validate() methods will recursively descend into all children of the + window if it has this style flag set. + + @b wxWS_EX_BLOCK_EVENTS + + + Normally, the command + events are propagated upwards to the window parent recursively until a handler + for them is found. Using this style allows to prevent them from being + propagated beyond this window. Notice that wxDialog has this style on by + default for the reasons explained in the + @ref overview_eventprocessing "event processing overview". + + @b wxWS_EX_TRANSIENT + + + This can be used to prevent a + window from being used as an implicit parent for the dialogs which were + created without a parent. It is useful for the windows which can disappear at + any moment as creating children of such windows results in fatal problems. + + @b wxWS_EX_CONTEXTHELP + + + Under Windows, puts a query + button on the caption. When pressed, Windows will go into a context-sensitive + help mode and wxWidgets will send a wxEVT_HELP event if the user clicked on an + application window. + This style cannot be used together with wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so + these two styles are automatically turned of if this one is used. + + @b wxWS_EX_PROCESS_IDLE + + + This window should always process idle events, even + if the mode set by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. + + @b wxWS_EX_PROCESS_UI_UPDATES + + + This window should always process UI update events, + even if the mode set by wxUpdateUIEvent::SetMode is + wxUPDATE_UI_PROCESS_SPECIFIED. + */ + void SetExtraStyle(long exStyle); + + /** + This sets the window to receive keyboard input. + + @sa HasFocus(), wxFocusEvent, wxPanel::SetFocus, + wxPanel::SetFocusIgnoringChildren + */ + virtual void SetFocus(); + + /** + This function is called by wxWidgets keyboard navigation code when the user + gives the focus to this window from keyboard (e.g. using @c TAB key). + By default this method simply calls SetFocus() but + can be overridden to do something in addition to this in the derived classes. + */ + virtual void SetFocusFromKbd(); + + /** + Sets the font for this window. This function should not be called for the + parent window if you don't want its font to be inherited by its children, + use SetOwnFont() instead in this case and + see InheritAttributes() for more + explanations. + + Please notice that the given font is not automatically used for + wxPaintDC objects associated with this window, you need to + call wxDC::SetFont too. However this font is used by + any standard controls for drawing their text as well as by + GetTextExtent(). + + @param font + Font to associate with this window, pass + wxNullFont to reset to the default font. + + @returns @true if the want was really changed, @false if it was already set + to this font and so nothing was done. + + @sa GetFont(), InheritAttributes() + */ + bool SetFont(const wxFont& font); + + /** + Sets the foreground colour of the window. + + Please see InheritAttributes() for + explanation of the difference between this method and + SetOwnForegroundColour(). + + @param colour + The colour to be used as the foreground colour, pass + wxNullColour to reset to the default colour. + + @remarks The interpretation of foreground colour is open to + interpretation according to the window class; it may + be the text colour or other colour, or it may not be + used at all. + + @sa GetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour(), ShouldInheritColours() + */ + virtual void SetForegroundColour(const wxColour& colour); + + /** + Sets the help text to be used as context-sensitive help for this window. + + Note that the text is actually stored by the current wxHelpProvider + implementation, + and not in the window object itself. + + @sa GetHelpText(), wxHelpProvider + */ + virtual void SetHelpText(const wxString& helpText); + + /** + Sets the identifier of the window. + + @remarks Each window has an integer identifier. If the application has + not provided one, an identifier will be generated. + Normally, the identifier should be provided on + creation and should not be modified subsequently. + + @sa GetId(), @ref overview_windowids "Window identifiers" + */ + void SetId(int id); + + /** + Sets the initial window size if none is given (i.e. at least one of the + components of the size passed to ctor/Create() is wxDefaultCoord). + */ + virtual void SetInitialBestSize(const wxSize& size); + + /** + A @e smart SetSize that will fill in default size components with the + window's @e best size values. Also sets the window's minsize to + the value passed in for use with sizers. This means that if a full or + partial size is passed to this function then the sizers will use that + size instead of the results of GetBestSize to determine the minimum + needs of the window for layout. + + Most controls will use this to set their initial size, and their min + size to the passed in value (if any.) + + @sa SetSize(), GetBestSize(), GetEffectiveMinSize() + */ + void SetInitialSize(const wxSize& size = wxDefaultSize); + + /** + Sets the window's label. + + @param label + The window label. + + @sa GetLabel() + */ + virtual void SetLabel(const wxString& label); + + /** + Sets the maximum client size of the window, to indicate to the sizer + layout mechanism that this is the maximum possible size of its client area. + + @sa SetMaxSize() + */ + void SetMaxClientSize(const wxSize& size); + + /** + Sets the maximum size of the window, to indicate to the sizer layout mechanism + that this is the maximum possible size. + + @sa SetMaxClientSize() + */ + void SetMaxSize(const wxSize& size); + + /** + Sets the minimum client size of the window, to indicate to the sizer + layout mechanism that this is the minimum required size of window's client + area. You may need to call this if you change the window size after + construction and before adding to its parent sizer. + + @sa SetMinSize() + */ + void SetMinClientSize(const wxSize& size); + + /** + Sets the minimum size of the window, to indicate to the sizer layout mechanism + that this is the minimum required size. You may need to call this + if you change the window size after construction and before adding + to its parent sizer. + + @sa SetMinClientSize() + */ + void SetMinSize(const wxSize& size); + + /** + Sets the window's name. + + @param name + A name to set for the window. + + @sa GetName() + */ + virtual void SetName(const wxString& name); + + /** + Sets the background colour of the window but prevents it from being inherited + by the children of this window. + + @sa SetBackgroundColour(), InheritAttributes() + */ + void SetOwnBackgroundColour(const wxColour& colour); + + /** + Sets the font of the window but prevents it from being inherited by the + children of this window. + + @sa SetFont(), InheritAttributes() + */ + void SetOwnFont(const wxFont& font); + + /** + Sets the foreground colour of the window but prevents it from being inherited + by the children of this window. + + @sa SetForegroundColour(), InheritAttributes() + */ + void SetOwnForegroundColour(const wxColour& colour); + + /** + Obsolete - use wxDC::SetPalette instead. + */ + virtual void SetPalette(wxPalette* palette); + + /** + Sets the position of one of the built-in scrollbars. + + @param orientation + Determines the scrollbar whose position is to be set. May be wxHORIZONTAL or + wxVERTICAL. + + @param pos + Position in scroll units. + + @param refresh + @true to redraw the scrollbar, @false otherwise. + + @remarks This function does not directly affect the contents of the + window: it is up to the application to take note of + scrollbar attributes and redraw contents accordingly. + + @sa SetScrollbar(), GetScrollPos(), GetScrollThumb(), + wxScrollBar, wxScrolledWindow + */ + virtual void SetScrollPos(int orientation, int pos, + bool refresh = @true); + + /** + Sets the scrollbar properties of a built-in scrollbar. + + @param orientation + Determines the scrollbar whose page size is to be set. May be wxHORIZONTAL or + wxVERTICAL. + + @param position + The position of the scrollbar in scroll units. + + @param thumbSize + The size of the thumb, or visible portion of the scrollbar, in scroll units. + + @param range + The maximum position of the scrollbar. + + @param refresh + @true to redraw the scrollbar, @false otherwise. + + @remarks Let's say you wish to display 50 lines of text, using the same + font. The window is sized so that you can only see 16 + lines at a time. + + @sa @ref overview_scrollingoverview "Scrolling overview", wxScrollBar, + wxScrolledWindow, wxScrollWinEvent + */ + virtual void SetScrollbar(int orientation, int position, + int thumbSize, + int range, + bool refresh = @true); + + //@{ + /** + Sets the size of the window in pixels. + + @param x + Required x position in pixels, or wxDefaultCoord to indicate that the existing + value should be used. + + @param y + Required y position in pixels, or wxDefaultCoord to indicate that the existing + value should be used. + + @param width + Required width in pixels, or wxDefaultCoord to indicate that the existing + value should be used. + + @param height + Required height position in pixels, or wxDefaultCoord to indicate that the + existing + value should be used. + + @param size + wxSize object for setting the size. + + @param rect + wxRect object for setting the position and size. + + @param sizeFlags + Indicates the interpretation of other parameters. It is a bit list of the + following: + + wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate + a wxWidgets-supplied default width. + + wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate + a wxWidgets-supplied default height. + + wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate + a wxWidgets-supplied default size. + + wxSIZE_USE_EXISTING: existing dimensions should be used + if wxDefaultCoord values are supplied. + + wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of + wxDefaultCoord) to be interpreted + as real dimensions, not default values. + wxSIZE_FORCE: normally, if the position and the size of the window are + already the same as the parameters of this function, nothing is done. but with + this flag a window resize may be forced even in this case (supported in wx + 2.6.2 and later and only implemented for MSW and ignored elsewhere currently) + + @remarks The second form is a convenience for calling the first form with + default x and y parameters, and must be used with + non-default width and height values. + + @sa Move() + */ + virtual void SetSize(int x, int y, int width, int height, + int sizeFlags = wxSIZE_AUTO); + virtual void SetSize(const wxRect& rect); + virtual void SetSize(int width, int height); + virtual void SetSize(const wxSize& size); + //@} + + /** + Use of this function for windows which are not toplevel windows + (such as wxDialog or wxFrame) is discouraged. Please use + SetMinSize() and SetMaxSize() + instead. + + @sa wxTopLevelWindow::SetSizeHints. + */ + + + /** + Sets the window to have the given layout sizer. The window + will then own the object, and will take care of its deletion. + If an existing layout constraints object is already owned by the + window, it will be deleted if the deleteOld parameter is @true. + + Note that this function will also call + SetAutoLayout() implicitly with @true + parameter if the @e sizer is non-@NULL and @false otherwise. + + @param sizer + The sizer to set. Pass @NULL to disassociate and conditionally delete + the window's sizer. See below. + + @param deleteOld + If @true (the default), this will delete any pre-existing sizer. + Pass @false if you wish to handle deleting the old sizer yourself. + + @remarks SetSizer now enables and disables Layout automatically, but + prior to wxWidgets 2.3.3 the following applied: + */ + void SetSizer(wxSizer* sizer, bool deleteOld=@true); + + /** + This method calls SetSizer() and then + wxSizer::SetSizeHints which sets the initial + window size to the size needed to accommodate all sizer elements and sets the + size hints which, if this window is a top level one, prevent the user from + resizing it to be less than this minimial size. + */ + void SetSizerAndFit(wxSizer* sizer, bool deleteOld=@true); + + /** + This function tells a window if it should use the system's "theme" code + to draw the windows' background instead if its own background drawing + code. This does not always have any effect since the underlying platform + obviously needs to support the notion of themes in user defined windows. + One such platform is GTK+ where windows can have (very colourful) backgrounds + defined by a user's selected theme. + + Dialogs, notebook pages and the status bar have this flag set to @true + by default so that the default look and feel is simulated best. + */ + virtual void SetThemeEnabled(bool enable); + + //@{ + /** + Attach a tooltip to the window. + + See also: GetToolTip(), + wxToolTip + */ + void SetToolTip(const wxString& tip); + void SetToolTip(wxToolTip* tip); + //@} + + /** + Set the transparency of the window. If the system supports transparent windows, + returns @true, otherwise returns @false and the window remains fully opaque. + See also CanSetTransparent(). + + The parameter @e alpha is in the range 0..255 where 0 corresponds to a + fully transparent window and 255 to the fully opaque one. The constants + @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be + used. + */ + bool SetTransparent(wxByte alpha); + + /** + Deletes the current validator (if any) and sets the window validator, having + called wxValidator::Clone to + create a new validator of this type. + */ + virtual void SetValidator(const wxValidator& validator); + + //@{ + /** + Sets the virtual size of the window in pixels. + */ + void SetVirtualSize(int width, int height); + void SetVirtualSize(const wxSize& size); + //@} + + //@{ + /** + Allows specification of minimum and maximum virtual window sizes. + If a pair of values is not set (or set to -1), the default values + will be used. + + @param minW + Specifies the minimum width allowable. + + @param minH + Specifies the minimum height allowable. + + @param maxW + Specifies the maximum width allowable. + + @param maxH + Specifies the maximum height allowable. + + @param minSize + Minimum size. + + @param maxSize + Maximum size. + + @remarks If this function is called, the user will not be able to size + the virtual area of the window outside the given + bounds. + */ + virtual void SetVirtualSizeHints(int minW, int minH, int maxW=-1, + int maxH=-1); + void SetVirtualSizeHints(const wxSize& minSize=wxDefaultSize, + const wxSize& maxSize=wxDefaultSize); + //@} + + /** + Identical to SetWindowStyleFlag(). + */ + void SetWindowStyle(long style); + + /** + Sets the style of the window. Please note that some styles cannot be changed + after the window creation and that Refresh() might + need to be be called after changing the others for the change to take place + immediately. + + See @ref overview_windowstyles "Window styles" for more information about flags. + + @sa GetWindowStyleFlag() + */ + virtual void SetWindowStyleFlag(long style); + + /** + This function can be called under all platforms but only does anything under + Mac OS X 10.3+ currently. Under this system, each of the standard control can + exist in several sizes which correspond to the elements of wxWindowVariant + enum: + + By default the controls use the normal size, of course, but this function can + be used to change this. + */ + void SetWindowVariant(wxWindowVariant variant); + + /** + Return @true from here to allow the colours of this window to be changed by + InheritAttributes(), returning @false + forbids inheriting them from the parent window. + + The base class version returns @false, but this method is overridden in + wxControl where it returns @true. + */ + virtual bool ShouldInheritColours(); + + /** + Shows or hides the window. You may need to call Raise() + for a top level window if you want to bring it to top, although this is not + needed if Show() is called immediately after the frame creation. + + @param show + If @true displays the window. Otherwise, hides it. + + @returns @true if the window has been shown or hidden or @false if nothing + was done because it already was in the requested + state. + + @sa IsShown(), Hide(), wxRadioBox::Show + */ + virtual bool Show(bool show = @true); + + /** + This function shows a window, like Show(), but using a + special visual effect if possible. + + Possible values for @e effect are: + + + wxSHOW_EFFECT_ROLL + + + Roll window effect + + wxSHOW_EFFECT_SLIDE + + + Sliding window effect + + wxSHOW_EFFECT_BLEND + + + Fade in or out effect + + wxSHOW_EFFECT_EXPAND + + + Expanding or collapsing effect + + For the roll and slide effects the @e dir parameter specifies the animation + direction: it can be one of @c wxTOP, @c wxBOTTOM, @c wxLEFT + or @c wxRIGHT. For the other effects, this parameter is unused. + + The @e timeout parameter specifies the time of the animation, in + milliseconds. If the default value of 0 is used, the default animation time + for the current platform is used. + + Currently this function is only implemented in wxMSW and does the same thing as + Show() in the other ports. + + This function is new since wxWidgets version 2.9.0 + + @sa HideWithEffect() + */ + virtual bool ShowWithEffect(wxShowEffect effect, + unsigned timeout = 0, + wxDirection dir = wxBOTTOM); + + /** + Reenables window updating after a previous call to + Freeze(). To really thaw the control, it must be called + exactly the same number of times as Freeze(). + + @sa wxWindowUpdateLocker + */ + virtual void Thaw(); + + /** + Turns the given @e flag on if it's currently turned off and vice versa. + This function cannot be used if the value of the flag is 0 (which is often + the case for default flags). + + Also, please notice that not all styles can be changed after the control + creation. + + @returns Returns @true if the style was turned on by this function, @false + if it was switched off. + + @sa SetWindowStyleFlag(), HasFlag() + */ + bool ToggleWindowStyle(int flag); + + /** + Transfers values from child controls to data areas specified by their + validators. Returns + @false if a transfer failed. + + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataFromWindow() of all child windows. + + @sa TransferDataToWindow(), wxValidator, Validate() + */ + virtual bool TransferDataFromWindow(); + + /** + Transfers values to child controls from data areas specified by their + validators. + + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataToWindow() of all child windows. + + @returns Returns @false if a transfer failed. + + @sa TransferDataFromWindow(), wxValidator, Validate() + */ + virtual bool TransferDataToWindow(); + + /** + Unregisters a system wide hotkey. + + @param hotkeyId + Numeric identifier of the hotkey. Must be the same id that was passed to + RegisterHotKey. + + @returns @true if the hotkey was unregistered successfully, @false if the + id was invalid. + + @remarks This function is currently only implemented under MSW. + + @sa RegisterHotKey() + */ + bool UnregisterHotKey(int hotkeyId); + + /** + Unreserve an ID or range of IDs that was reserved by NewControlId(). + + See @ref overview_windowidsoverview "Window IDs overview" for more information. + + @param id + The starting ID of the range of IDs to unreserve. + + @param count + The number of sequential IDs to unreserve. + + @sa NewControlId(), wxIdManager, @ref overview_windowidsoverview + "Window IDs overview" + */ + static void UnreserveControlId(wxWindowID id, int count = 1); + + /** + Calling this method immediately repaints the invalidated area of the window and + all of its children recursively while this would usually only happen when the + flow of control returns to the event loop. + Notice that this function doesn't invalidate any area of the window so + nothing happens if nothing has been invalidated (i.e. marked as requiring + a redraw). Use Refresh() first if you want to + immediately redraw the window unconditionally. + */ + virtual void Update(); + + /** + This function sends wxUpdateUIEvents to + the window. The particular implementation depends on the window; for + example a wxToolBar will send an update UI event for each toolbar button, + and a wxFrame will send an update UI event for each menubar menu item. + You can call this function from your application to ensure that your + UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers + are concerned). This may be necessary if you have called + wxUpdateUIEvent::SetMode or + wxUpdateUIEvent::SetUpdateInterval to + limit the overhead that wxWidgets incurs by sending update UI events in idle + time. + + @e flags should be a bitlist of one or more of the following values. + If you are calling this function from an OnInternalIdle or OnIdle + function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since + this tells the window to only update the UI elements that need + to be updated in idle time. Some windows update their elements + only when necessary, for example when a menu is about to be shown. + The following is an example of how to call UpdateWindowUI from + an idle function. + + @sa wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle() + */ + virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE); + + /** + Validates the current values of the child controls using their validators. + + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call Validate() of all child windows. + + @returns Returns @false if any of the validations failed. + + @sa TransferDataFromWindow(), TransferDataToWindow(), + wxValidator + */ + virtual bool Validate(); + + /** + Moves the pointer to the given position on the window. + + @b NB: This function is not supported under Mac because Apple Human + Interface Guidelines forbid moving the mouse cursor programmatically. + + @param x + The new x position for the cursor. + + @param y + The new y position for the cursor. + */ + void WarpPointer(int x, int y); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + Find the deepest window at the given mouse position in screen coordinates, + returning the window if found, or @NULL if not. +*/ +wxWindow * wxFindWindowAtPoint(const wxPoint& pt); + +/** + Find the deepest window at the mouse pointer position, returning the window + and current pointer position in screen coordinates. +*/ +wxWindow * wxFindWindowAtPointer(wxPoint& pt); + +/** + Gets the currently active window (implemented for MSW and GTK only currently, + always returns @NULL in the other ports). +*/ +wxWindow * wxGetActiveWindow(); + +/** + Returns the first top level parent of the given window, or in other words, the + frame or dialog containing it, or @NULL. +*/ +wxWindow * wxGetTopLevelParent(wxWindow win); + diff --git a/interface/windowid.h b/interface/windowid.h new file mode 100644 index 0000000000..47bfcf4886 --- /dev/null +++ b/interface/windowid.h @@ -0,0 +1,42 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: windowid.h +// Purpose: documentation for wxIdManager class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIdManager + @wxheader{windowid.h} + + wxIdManager is responsible for allocating and releasing window IDs. It + is used by wxWindow::NewControlId and + wxWindow::UnreserveControlId, and can also + be used be used directly. + + @library{wxcore} + @category{FIXME} + + @seealso + wxWindow::NewControlId, wxWindow::UnreserveControlId, @ref + overview_windowidsoverview "Window IDs overview" +*/ +class wxIdManager +{ +public: + /** + Called directly by wxWindow::NewControlId, + this function will create a new ID or range of IDs. The IDs will be + reserved until assigned to a wxWindowIDRef + or unreserved with UnreserveControlId(). + Only ID values that are not assigned to a wxWindowIDRef + need to be unreserved. + + @param count + The number of sequential IDs to reserve. + + @returns The value of the first ID in the sequence, or wxID_NONE. + */ + static wxWindowID ReserveControlId(int count = 1); +}; diff --git a/interface/wizard.h b/interface/wizard.h new file mode 100644 index 0000000000..f20c238699 --- /dev/null +++ b/interface/wizard.h @@ -0,0 +1,510 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wizard.h +// Purpose: documentation for wxWizardPage class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWizardPage + @wxheader{wizard.h} + + wxWizardPage is one of the screens in wxWizard: it must + know what are the following and preceding pages (which may be @NULL for the + first/last page). Except for this extra knowledge, wxWizardPage is just a + panel, so the controls may be placed directly on it in the usual way. + + This class allows the programmer to decide the order of pages in the wizard + dynamically (during run-time) and so provides maximal flexibility. Usually, + however, the order of pages is known in advance in which case + wxWizardPageSimple class is enough and it is simpler + to use. + + @library{wxadv} + @category{miscwnd} + + @seealso + wxWizard, @ref overview_samplewizard "wxWizard sample" +*/ +class wxWizardPage : public wxPanel +{ +public: + /** + Constructor accepts an optional bitmap which will be used for this page + instead of the default one for this wizard (note that all bitmaps used should + be of the same size). Notice that no other parameters are needed because the + wizard will resize and reposition the page anyhow. + + @param parent + The parent wizard + + @param bitmap + The page-specific bitmap if different from the global one + */ + wxWizardPage(wxWizard* parent, + const wxBitmap& bitmap = wxNullBitmap); + + /** + This method is called by wxWizard to get the bitmap to display alongside the + page. By default, @c m_bitmap member variable which was set in the + @ref wxwizardpage() constructor. + + If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned), + the default bitmap for the wizard should be used. + + The only cases when you would want to override this function is if the page + bitmap depends dynamically on the user choices, i.e. almost never. + */ + wxBitmap GetBitmap(); + + /** + Get the page which should be shown when the user chooses the @c "Next" + button: if @NULL is returned, this button will be disabled. The last + page of the wizard will usually return @NULL from here, but the others + will not. + + @sa GetPrev() + */ + wxWizardPage* GetNext(); + + /** + Get the page which should be shown when the user chooses the @c "Back" + button: if @NULL is returned, this button will be disabled. The first + page of the wizard will usually return @NULL from here, but the others + will not. + + @sa GetNext() + */ + wxWizardPage* GetPrev(); +}; + + +/** + @class wxWizardEvent + @wxheader{wizard.h} + + wxWizardEvent class represents an event generated by the + wizard: this event is first sent to the page itself and, + if not processed there, goes up the window hierarchy as usual. + + @library{wxadv} + @category{events} + + @seealso + wxWizard, @ref overview_samplewizard "wxWizard sample" +*/ +class wxWizardEvent : public wxNotifyEvent +{ +public: + /** + Constructor. It is not normally used by the user code as the objects of this + type are constructed by wxWizard. + */ + wxWizardEvent(wxEventType type = wxEVT_@NULL, int id = -1, + bool direction = @true); + + /** + Return the direction in which the page is changing: for @c + EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or + @false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if + we came from the previous page and @false if we returned from the next + one. + */ + bool GetDirection(); + + /** + Returns the wxWizardPage which was active when this + event was generated. + */ + wxWizardPage* GetPage(); +}; + + +/** + @class wxWizardPageSimple + @wxheader{wizard.h} + + wxWizardPageSimple is the simplest possible + wxWizardPage implementation: it just returns the + pointers given to its constructor from GetNext() and GetPrev() functions. + + This makes it very easy to use the objects of this class in the wizards where + the pages order is known statically - on the other hand, if this is not the + case you must derive your own class from wxWizardPage + instead. + + @library{wxadv} + @category{miscwnd} + + @seealso + wxWizard, @ref overview_samplewizard "wxWizard sample" +*/ +class wxWizardPageSimple : public wxWizardPage +{ +public: + /** + Constructor takes the previous and next pages. They may be modified later by + SetPrev() or + SetNext(). + */ + wxWizardPageSimple(wxWizard* parent = @NULL, + wxWizardPage* prev = @NULL, + wxWizardPage* next = @NULL, + const wxBitmap& bitmap = wxNullBitmap); + + /** + A convenience function to make the pages follow each other. + + Example: + */ + static void Chain(wxWizardPageSimple* first, + wxWizardPageSimple* second); + + /** + Sets the next page. + */ + void SetNext(wxWizardPage* next); + + /** + Sets the previous page. + */ + void SetPrev(wxWizardPage* prev); +}; + + +/** + @class wxWizard + @wxheader{wizard.h} + + wxWizard is the central class for implementing 'wizard-like' dialogs. These + dialogs are mostly familiar to Windows users and are nothing other than a + sequence of 'pages', each displayed inside a dialog which has the + buttons to navigate to the next (and previous) pages. + + The wizards are typically used to decompose a complex dialog into several + simple steps and are mainly useful to the novice users, hence it is important + to keep them as simple as possible. + + To show a wizard dialog, you must first create an instance of the wxWizard class + using either the non-default constructor or a default one followed by call to + the + wxWizard::Create function. Then you should add all pages you + want the wizard to show and call wxWizard::RunWizard. + Finally, don't forget to call @c wizard-Destroy(), otherwise your application + will hang on exit due to an undestroyed window. + + You can supply a bitmap to display on the left of the wizard, either for all + pages + or for individual pages. If you need to have the bitmap resize to the height of + the wizard, + call wxWizard::SetBitmapPlacement and if necessary, + wxWizard::SetBitmapBackgroundColour and wxWizard::SetMinimumBitmapWidth. + + To make wizard pages scroll when the display is too small to fit the whole + dialog, you can switch + layout adaptation on globally with wxDialog::EnableLayoutAdaptation or + per dialog with wxDialog::SetLayoutAdaptationMode. For more + about layout adaptation, see @ref overview_autoscrollingdialogs "Automatic + scrolling dialogs". + + @library{wxadv} + @category{cmndlg} + + @seealso + wxWizardEvent, wxWizardPage, @ref overview_samplewizard "wxWizard sample" +*/ +class wxWizard : public wxDialog +{ +public: + //@{ + /** + Constructor which really creates the wizard -- if you use this constructor, you + shouldn't call Create(). + + Notice that unlike almost all other wxWidgets classes, there is no @e size + parameter in the wxWizard constructor because the wizard will have a predefined + default size by default. If you want to change this, you should use the + GetPageAreaSizer() function. + + @param parent + The parent window, may be @NULL. + + @param id + The id of the dialog, will usually be just -1. + + @param title + The title of the dialog. + + @param bitmap + The default bitmap used in the left side of the wizard. See + also GetBitmap. + + @param pos + The position of the dialog, it will be centered on the screen + by default. + + @param style + Window style is passed to wxDialog. + */ + wxWizard(); + wxWizard(wxWindow* parent, int id = -1, + const wxString& title = wxEmptyString, + const wxBitmap& bitmap = wxNullBitmap, + const wxPoint& pos = wxDefaultPosition, + long style = wxDEFAULT_DIALOG_STYLE); + //@} + + /** + Creates the wizard dialog. Must be called if the default constructor had been + used to create the object. + + Notice that unlike almost all other wxWidgets classes, there is no @e size + parameter in the wxWizard constructor because the wizard will have a predefined + default size by default. If you want to change this, you should use the + GetPageAreaSizer() function. + + @param parent + The parent window, may be @NULL. + + @param id + The id of the dialog, will usually be just -1. + + @param title + The title of the dialog. + + @param bitmap + The default bitmap used in the left side of the wizard. See + also GetBitmap. + + @param pos + The position of the dialog, it will be centered on the screen + by default. + + @param style + Window style is passed to wxDialog. + */ + bool Create(wxWindow* parent, int id = -1, + const wxString& title = wxEmptyString, + const wxBitmap& bitmap = wxNullBitmap, + const wxPoint& pos = wxDefaultPosition, + long style = wxDEFAULT_DIALOG_STYLE); + + /** + This method is obsolete, use + GetPageAreaSizer() instead. + + Sets the page size to be big enough for all the pages accessible via the + given @e firstPage, i.e. this page, its next page and so on. + + This method may be called more than once and it will only change the page size + if the size required by the new page is bigger than the previously set one. + This is useful if the decision about which pages to show is taken during + run-time, as in this case, the wizard won't be able to get to all pages starting + from a single one and you should call @e Fit separately for the others. + */ + void FitToPage(const wxWizardPage* firstPage); + + /** + Returns the bitmap used for the wizard. + */ + const wxBitmap GetBitmap(); + + /** + Returns the colour that should be used to fill the area not taken up by the + wizard or page bitmap, + if a non-zero bitmap placement flag has been set. + + See also SetBitmapPlacement(). + */ + const wxColour GetBitmapBackgroundColour(); + + /** + Returns the flags indicating how the wizard or page bitmap should be expanded + and positioned to fit the + page height. By default, placement is 0 (no expansion is done). + + See also SetBitmapPlacement() for the possible values. + */ + int GetBitmapPlacement(); + + /** + Get the current page while the wizard is running. @NULL is returned if + RunWizard() is not being executed now. + */ + wxWizardPage* GetCurrentPage(); + + /** + Returns the minimum width for the bitmap that will be constructed to contain + the actual wizard or page bitmap + if a non-zero bitmap placement flag has been set. + + See also SetBitmapPlacement(). + */ + int GetMinimumBitmapWidth(); + + /** + Returns pointer to page area sizer. The wizard is laid out using sizers and + the page area sizer is the place-holder for the pages. All pages are resized + before + being shown to match the wizard page area. + + Page area sizer has a minimal size that is the maximum of several values. First, + all pages (or other objects) added to the sizer. Second, all pages reachable + by repeatedly applying + wxWizardPage::GetNext to + any page inserted into the sizer. Third, + the minimal size specified using SetPageSize() and + FitToPage(). Fourth, the total wizard height may + be increased to accommodate the bitmap height. Fifth and finally, wizards are + never smaller than some built-in minimal size to avoid wizards that are too + small. + + The caller can use wxSizer::SetMinSize to enlarge it + beyond the minimal size. If @c wxRESIZE_BORDER was passed to constructor, user + can resize wizard and consequently the page area (but not make it smaller than + the + minimal size). + + It is recommended to add the first page to the page area sizer. For simple + wizards, + this will enlarge the wizard to fit the biggest page. For non-linear wizards, + the first page of every separate chain should be added. Caller-specified size + can be accomplished using wxSizer::SetMinSize. + + Adding pages to the page area sizer affects the default border width around page + area that can be altered with SetBorder(). + */ + virtual wxSizer* GetPageAreaSizer(); + + /** + Returns the size available for the pages. + */ + wxSize GetPageSize(); + + /** + Return @true if this page is not the last one in the wizard. The base + class version implements this by calling + @ref wxWizardPage::getnext page-GetNext but this could be undesirable if, + for example, the pages are created on demand only. + + @sa HasPrevPage() + */ + virtual bool HasNextPage(wxWizardPage * page); + + /** + Returns @true if this page is not the last one in the wizard. The base + class version implements this by calling + @ref wxWizardPage::getprev page-GetPrev but this could be undesirable if, + for example, the pages are created on demand only. + + @sa HasNextPage() + */ + virtual bool HasPrevPage(wxWizardPage * page); + + /** + Executes the wizard starting from the given page, returning @true if it was + successfully finished or @false if user cancelled it. The @e firstPage + can not be @NULL. + */ + bool RunWizard(wxWizardPage* firstPage); + + /** + Sets the bitmap used for the wizard. + */ + void SetBitmap(const wxBitmap& bitmap); + + /** + Sets the colour that should be used to fill the area not taken up by the wizard + or page bitmap, + if a non-zero bitmap placement flag has been set. + + See also SetBitmapPlacement(). + */ + void SetBitmapBackgroundColour(const wxColour& colour); + + /** + Sets the flags indicating how the wizard or page bitmap should be expanded and + positioned to fit the + page height. By default, placement is 0 (no expansion is done). @e placement is + a bitlist with the + following possible values: + + @b wxWIZARD_VALIGN_TOP + + + Aligns the bitmap at the top. + + @b wxWIZARD_VALIGN_CENTRE + + + Centres the bitmap vertically. + + @b wxWIZARD_VALIGN_BOTTOM + + + Aligns the bitmap at the bottom. + + @b wxWIZARD_HALIGN_LEFT + + + Left-aligns the bitmap. + + @b wxWIZARD_HALIGN_CENTRE + + + Centres the bitmap horizontally. + + @b wxWIZARD_HALIGN_RIGHT + + + Right-aligns the bitmap. + + @b wxWIZARD_TILE + + + + See also SetMinimumBitmapWidth(). + */ + void SetBitmapPlacement(int placement); + + /** + Sets width of border around page area. Default is zero. For backward + compatibility, if there are no pages in + GetPageAreaSizer(), the default is 5 pixels. + + If there is a five point border around all controls in a page and the border + around + page area is left as zero, a five point white space along all dialog borders + will be added to the control border in order to space page controls ten points + from the dialog + border and non-page controls. + */ + void SetBorder(int border); + + /** + Sets the minimum width for the bitmap that will be constructed to contain the + actual wizard or page bitmap + if a non-zero bitmap placement flag has been set. If this is not set when using + bitmap placement, the initial + layout may be incorrect. + + See also SetBitmapPlacement(). + */ + void SetMinimumBitmapWidth(int width); + + /** + This method is obsolete, use + GetPageAreaSizer() instead. + + Sets the minimal size to be made available for the wizard pages. The wizard + will take into account the size of the bitmap (if any) itself. Also, the + wizard will never be smaller than the default size. + + The recommended way to use this function is to lay out all wizard pages using + the sizers (even though the wizard is not resizeable) and then use + wxSizer::CalcMin in a loop to calculate the maximum + of minimal sizes of the pages and pass it to SetPageSize(). + */ + void SetPageSize(const wxSize& sizePage); +}; diff --git a/interface/wrapsizer.h b/interface/wrapsizer.h new file mode 100644 index 0000000000..e79832704c --- /dev/null +++ b/interface/wrapsizer.h @@ -0,0 +1,48 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wrapsizer.h +// Purpose: documentation for wxWrapSizer class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWrapSizer + @wxheader{wrapsizer.h} + + A wrap sizer lays out its items in a single line, like a box sizer -- as long + as there is space available in that direction. Once all available space in + the primary direction has been used, a new line is added and items are added + there. + + So a wrap sizer has a primary orientation for adding items, and adds lines + as needed in the secondary direction. + + @library{wxcore} + @category{winlayout} + + @seealso + wxBoxSizer, wxSizer, @ref overview_sizeroverview "Sizer overview" +*/ +class wxWrapSizer : public wxBoxSizer +{ +public: + /** + Constructor for a wxWrapSizer. @e orient determines the primary direction of + the sizer (the most common case being @c wxHORIZONTAL). The flags + parameter may have the value @c wxEXTEND_LAST_ON_EACH_LINE which will + cause the last item on each line to use any remaining space on that line. + */ + wxWrapSizer(int orient, int flags); + + /** + Not used by an application. This is the mechanism by which sizers can inform + sub-items of the first determined size component. The sub-item can then better + determine its size requirements. + + Returns @true if the information was used (and the sub-item min size was + updated). + */ + bool InformFirstDirection(int direction, int size, + int availableOtherDir); +}; diff --git a/interface/wupdlock.h b/interface/wupdlock.h new file mode 100644 index 0000000000..a16f2d9dea --- /dev/null +++ b/interface/wupdlock.h @@ -0,0 +1,52 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wupdlock.h +// Purpose: documentation for wxWindowUpdateLocker class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWindowUpdateLocker + @wxheader{wupdlock.h} + + This tiny class prevents redrawing of a wxWindow during its + lifetime by using wxWindow::Freeze and + wxWindow::Thaw methods. It is typically used for creating + automatic objects to temporarily suppress window updates before a batch of + operations is performed: + + @code + void MyFrame::Foo() + { + m_text = new wxTextCtrl(this, ...); + + wxWindowUpdateLocker noUpdates(m_text); + m_text-AppendText(); + ... many other operations with m_text... + m_text-WriteText(); + } + @endcode + + Using this class is easier and safer than calling + wxWindow::Freeze and wxWindow::Thaw because you + don't risk to forget calling the latter. + + @library{wxbase} + @category{FIXME} +*/ +class wxWindowUpdateLocker +{ +public: + /** + Creates an object preventing the updates of the specified @e win. The + parameter must be non-@NULL and the window must exist for longer than + wxWindowUpdateLocker object itself. + */ + wxWindowUpdateLocker(wxWindow * win); + + /** + Destructor reenables updates for the window this object is associated with. + */ + ~wxWindowUpdateLocker(); +}; diff --git a/interface/wxcrt.h b/interface/wxcrt.h new file mode 100644 index 0000000000..ba023ef432 --- /dev/null +++ b/interface/wxcrt.h @@ -0,0 +1,105 @@ +///////////////////////////////////////////////////////////////////////////// + // Name: wxcrt.h + // Purpose: documentation for global functions + // Author: wxWidgets team + // RCS-ID: $Id$ + // Licence: wxWindows license + ///////////////////////////////////////////////////////////////////////////// + + /** + Returns a negative value, 0, or positive value if @e p1 is less than, equal + to or greater than @e p2. The comparison is case-sensitive. + + This function complements the standard C function @e stricmp() which performs + case-insensitive comparison. +*/ +int wxStrcmp(const char * p1, const char * p2); + + + /** + @b NB: This function is obsolete, use wxString instead. + + A macro defined as: + @code + #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) + @endcode +*/ +bool wxStringEq(const wxString& s1, const wxString& s2); + +/** + @b NB: This function is obsolete, use wxString::Find instead. + + Returns @true if the substring @e s1 is found within @e s2, + ignoring case if @e exact is @false. If @e subString is @false, + no substring matching is done. +*/ +bool wxStringMatch(const wxString& s1, const wxString& s2, + bool subString = @true, + bool exact = @false); + +/** + This function replaces the dangerous standard function @c sprintf() and is + like @c snprintf() available on some platforms. The only difference with + sprintf() is that an additional argument - buffer size - is taken and the + buffer is never overflowed. + + Returns the number of characters copied to the buffer or -1 if there is not + enough space. + + @sa wxVsnprintf, wxString::Printf +*/ +int wxSnprintf(wxChar * buf, size_t len, const wxChar * format, + ...); + +/** + This is a convenience function wrapping + wxStringTokenizer which simply returns all tokens + found in the given @e str in an array. + + Please see + wxStringTokenizer::wxStringTokenizer + for the description of the other parameters. +*/ +wxArrayString wxStringTokenize(const wxString& str, + const wxString& delims = wxDEFAULT_DELIMITERS, + wxStringTokenizerMode mode = wxTOKEN_DEFAULT); + +/** + This is a safe version of standard function @e strlen(): it does exactly the + same thing (i.e. returns the length of the string) except that it returns 0 if + @e p is the @NULL pointer. +*/ +size_t wxStrlen(const char * p); + +/** + The same as wxSnprintf but takes a @c va_list + argument instead of arbitrary number of parameters. + + Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports + positional arguments (see wxString::Printf for more information). + However other functions of the same family (wxPrintf, wxSprintf, wxFprintf, + wxVfprintf, + wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional + parameters + even when @c wxUSE_PRINTF_POS_PARAMS is 1. + + @sa wxSnprintf, wxString::PrintfV +*/ +int wxVsnprintf(wxChar * buf, size_t len, const wxChar * format, + va_list argPtr); + +/** + Returns @true if the pointer is either @NULL or points to an empty + string, @false otherwise. +*/ +bool wxIsEmpty(const char * p); + +/** + Returns a negative value, 0, or positive value if @e p1 is less than, equal + to or greater than @e p2. The comparison is case-insensitive. + + This function complements the standard C function @e strcmp() which performs + case-sensitive comparison. +*/ +int wxStricmp(const char * p1, const char * p2); + diff --git a/interface/xml/xml.h b/interface/xml/xml.h new file mode 100644 index 0000000000..3925e340f3 --- /dev/null +++ b/interface/xml/xml.h @@ -0,0 +1,490 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: xml/xml.h +// Purpose: documentation for wxXmlNode class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxXmlNode + @headerfile xml.h wx/xml/xml.h + + Represents a node in an XML document. See wxXmlDocument. + + Node has a name and may have content and attributes. Most common node types are + @c wxXML_TEXT_NODE (name and attributes are irrelevant) and + @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element + with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE + with content="hi"). + + If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to + wxXmlDocument::Load (default is UTF-8). + + @library{wxxml} + @category{xml} + + @seealso + wxXmlDocument, wxXmlAttribute +*/ +class wxXmlNode +{ +public: + //@{ + /** + A simplified version of the first constructor form, assuming a @NULL parent. + */ + wxXmlNode(wxXmlNode* parent, wxXmlNodeType type, + const wxString& name, + const wxString& content = wxEmptyString, + wxXmlAttribute* attrs = @NULL, + wxXmlNode* next = @NULL, int lineNo = -1); + wxXmlNode(const wxXmlNode& node); + wxXmlNode(wxXmlNodeType type, const wxString& name, + const wxString& content = wxEmptyString, + int lineNo = -1); + //@} + + /** + The virtual destructor. Deletes attached children and attributes. + */ + ~wxXmlNode(); + + //@{ + /** + Appends given attribute to the list of attributes for this node. + */ + void AddAttribute(const wxString& name, const wxString& value); + void AddAttribute(wxXmlAttribute* attr); + //@} + + /** + Adds the given node as child of this node. To attach a second children to this + node, use the + SetNext() function of the @e child node. + */ + void AddChild(wxXmlNode* child); + + /** + Removes the first attributes which has the given @e name from the list of + attributes for this node. + */ + bool DeleteAttribute(const wxString& name); + + //@{ + /** + Returns the value of the attribute named @e attrName if it does exist. + If it does not exist, the @e defaultVal is returned. + */ + bool GetAttribute(const wxString& attrName, wxString* value); + wxString GetAttribute(const wxString& attrName, + const wxString& defaultVal); + //@} + + /** + Return a pointer to the first attribute of this node. + */ + wxXmlAttribute * GetAttributes(); + + /** + Returns the first child of this node. + To get a pointer to the second child of this node (if it does exist), use the + GetNext() function on the returned value. + */ + wxXmlNode* GetChildren(); + + /** + Returns the content of this node. Can be an empty string. + Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type) + the + content is an empty string. See GetNodeContent() for more details. + */ + wxString GetContent(); + + /** + Returns the number of nodes which separe this node from @c grandparent. + + This function searches only the parents of this node until it finds @c + grandparent + or the @NULL node (which is the parent of non-linked nodes or the parent of a + wxXmlDocument's root node). + */ + int GetDepth(wxXmlNode* grandparent = @NULL); + + /** + Returns line number of the node in the input XML file or -1 if it is unknown. + */ + int GetLineNumber(); + + /** + Returns the name of this node. Can be an empty string (e.g. for nodes of type + @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE). + */ + wxString GetName(); + + /** + Returns a pointer to the sibling of this node or @NULL if there are no + siblings. + */ + wxXmlNode* GetNext(); + + /** + Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c + wxXML_CDATA_SECTION_NODE. + This function is very useful since the XML snippet @c + "tagnametagcontent/tagname" is represented by + expat with the following tag tree: + or eventually: + An empty string is returned if the node has no children of type @c + wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty. + */ + wxString GetNodeContent(); + + /** + Returns a pointer to the parent of this node or @NULL if this node has no + parent. + */ + wxXmlNode* GetParent(); + + /** + Returns the type of this node. + */ + wxXmlNodeType GetType(); + + /** + Returns @true if this node has a attribute named @e attrName. + */ + bool HasAttribute(const wxString& attrName); + + /** + Inserts the @e child node after @e before_node in the children list. + If @e before_node is @NULL, then @e child is prepended to the list of + children and + becomes the first child of this node. + Returns @true if @e before_node has been found and the @e child node has been + inserted. + */ + bool InsertChild(wxXmlNode* child, wxXmlNode* before_node); + + /** + Returns @true if the content of this node is a string containing only + whitespaces (spaces, + tabs, new lines, etc). Note that this function is locale-independent since the + parsing of XML + documents must always produce the exact same tree regardless of the locale it + runs under. + */ + bool IsWhitespaceOnly(); + + /** + Removes the given node from the children list. Returns @true if the node was + found and removed + or @false if the node could not be found. + + Note that the caller is reponsible for deleting the removed node in order to + avoid memory leaks. + */ + bool RemoveChild(wxXmlNode* child); + + /** + Sets as first attribute the given wxXmlAttribute object. + The caller is responsible to delete any previously present attributes attached + to this node. + */ + void SetAttributes(wxXmlAttribute* attr); + + /** + Sets as first child the given node. The caller is responsible to delete any + previously present + children node. + */ + void SetChildren(wxXmlNode* child); + + /** + Sets the content of this node. + */ + void SetContent(const wxString& con); + + /** + Sets the name of this node. + */ + void SetName(const wxString& name); + + /** + Sets as sibling the given node. The caller is responsible to delete any + previously present + sibling node. + */ + void SetNext(wxXmlNode* next); + + /** + Sets as parent the given node. The caller is responsible to delete any + previously present + parent node. + */ + void SetParent(wxXmlNode* parent); + + /** + Sets the type of this node. + */ + void SetType(wxXmlNodeType type); + + /** + See the copy constructor for more info. + */ + wxXmlNode operator=(const wxXmlNode& node); +}; + + +/** + @class wxXmlAttribute + @headerfile xml.h wx/xml/xml.h + + Represents a node attribute. + + Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value + @c "hello.gif" and @c "id" is a attribute with value @c "3". + + @library{wxxml} + @category{xml} + + @seealso + wxXmlDocument, wxXmlNode +*/ +class wxXmlAttribute +{ +public: + //@{ + /** + Creates the attribute with given @e name and @e value. + If @e next is not @NULL, then sets it as sibling of this attribute. + */ + wxXmlAttribute(); + wxXmlAttribute(const wxString& name, const wxString& value, + wxXmlAttribute* next = @NULL); + //@} + + /** + The virtual destructor. + */ + ~wxXmlAttribute(); + + /** + Returns the name of this attribute. + */ + wxString GetName(); + + /** + Returns the sibling of this attribute or @NULL if there are no siblings. + */ + wxXmlAttribute* GetNext(); + + /** + Returns the value of this attribute. + */ + wxString GetValue(); + + /** + Sets the name of this attribute. + */ + void SetName(const wxString& name); + + /** + Sets the sibling of this attribute. + */ + void SetNext(wxXmlAttribute* next); + + /** + Sets the value of this attribute. + */ + void SetValue(const wxString& value); +}; + + +/** + @class wxXmlDocument + @headerfile xml.h wx/xml/xml.h + + This class holds XML data/document as parsed by XML parser in the root node. + + wxXmlDocument internally uses the expat library which comes with wxWidgets to + parse the given stream. + + A simple example of using XML classes is: + + @code + wxXmlDocument doc; + if (!doc.Load(wxT("myfile.xml"))) + return @false; + + // start processing the XML file + if (doc.GetRoot()-GetName() != wxT("myroot-node")) + return @false; + + wxXmlNode *child = doc.GetRoot()-GetChildren(); + while (child) { + + if (child-GetName() == wxT("tag1")) { + + // process text enclosed by tag1/tag1 + wxString content = child-GetNodeContent(); + + ... + + // process attributes of tag1 + wxString attrvalue1 = + child-GetAttribute(wxT("attr1"), + wxT("default-value")); + wxString attrvalue2 = + child-GetAttribute(wxT("attr2"), + wxT("default-value")); + + ... + + } else if (child-GetName() == wxT("tag2")) { + + // process tag2 ... + } + + child = child-GetNext(); + } + @endcode + + @b Note: if you want to preserve the original formatting of the loaded file + including whitespaces + and indentation, you need to turn off whitespace-only textnode removal and + automatic indentation: + + @code + wxXmlDocument doc; + doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES); + + // myfile2.xml will be indentic to myfile.xml saving it this way: + doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION); + @endcode + + Using default parameters, you will get a reformatted document which in general + is different from + the original loaded content: + + @code + wxXmlDocument doc; + doc.Load(wxT("myfile.xml")); + doc.Save(wxT("myfile2.xml")); // myfile2.xml != myfile.xml + @endcode + + @library{wxxml} + @category{xml} + + @seealso + wxXmlNode, wxXmlAttribute +*/ +class wxXmlDocument : public wxObject +{ +public: + //@{ + /** + Copy constructor. Deep copies all the XML tree of the given document. + */ + wxXmlDocument(); + wxXmlDocument(const wxString& filename); + wxXmlDocument(wxInputStream& stream); + wxXmlDocument(const wxXmlDocument& doc); + //@} + + /** + Virtual destructor. Frees the document root node. + */ + ~wxXmlDocument(); + + /** + Detaches the document root node and returns it. The document root node will be + set to @NULL + and thus IsOk() will return @false after calling this function. + + Note that the caller is reponsible for deleting the returned node in order to + avoid memory leaks. + */ + wxXmlNode* DetachRoot(); + + /** + Returns encoding of in-memory representation of the document + (same as passed to Load() or constructor, defaults to UTF-8). + + NB: this is meaningless in Unicode build where data are stored as @c wchar_t*. + */ + wxString GetEncoding(); + + /** + Returns encoding of document (may be empty). + + Note: this is the encoding original file was saved in, @b not the + encoding of in-memory representation! + */ + wxString GetFileEncoding(); + + /** + Returns the root node of the document. + */ + wxXmlNode* GetRoot(); + + /** + Returns the version of document. + This is the value in the @c ?xml version="1.0"? header of the XML document. + If the version attribute was not explicitely given in the header, this function + returns an empty string. + */ + wxString GetVersion(); + + /** + Returns @true if the document has been loaded successfully. + */ +#define bool IsOk() /* implementation is private */ + + //@{ + /** + , @b int@e flags = wxXMLDOC_NONE) + + Like above but takes the data from given input stream. + */ + bool Load(const wxString& filename); + int bool Load(wxInputStream& stream); + //@} + + //@{ + /** + Saves XML tree in the given output stream. See other overload for a description + of @c indentstep. + */ + bool Save(const wxString& filename, int indentstep = 1); + bool Save(wxOutputStream& stream, int indentstep = 1); + //@} + + /** + Sets the enconding of the document. + */ + void SetEncoding(const wxString& enc); + + /** + Sets the enconding of the file which will be used to save the document. + */ + void SetFileEncoding(const wxString& encoding); + + /** + Sets the root node of this document. Deletes previous root node. + Use DetachRoot() and then + SetRoot() if you want + to replace the root node without deleting the old document tree. + */ + void SetRoot(wxXmlNode* node); + + /** + Sets the version of the XML file which will be used to save the document. + */ + void SetVersion(const wxString& version); + + /** + Deep copies the given document. + */ + wxXmlDocument& operator operator=(const wxXmlDocument& doc); +}; diff --git a/interface/xrc/xmlres.h b/interface/xrc/xmlres.h new file mode 100644 index 0000000000..fab603bd97 --- /dev/null +++ b/interface/xrc/xmlres.h @@ -0,0 +1,446 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: xrc/xmlres.h +// Purpose: documentation for wxXmlResource class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxXmlResource + @headerfile xmlres.h wx/xrc/xmlres.h + + This is the main class for interacting with the XML-based resource system. + + The class holds XML resources from one or more .xml files, binary files or zip + archive files. + + See @ref overview_xrcoverview "XML-based resource system overview" for details. + + @library{wxxrc} + @category{xrc} +*/ +class wxXmlResource : public wxObject +{ +public: + //@{ + /** + Constructor. + + @param flags + wxXRC_USE_LOCALE: translatable strings will be translated via _(). + wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored + (useful for previews in XRC editors). wxXRC_NO_RELOADING will prevent the + XRC files from being reloaded from disk in case they have been modified there + since being last loaded (may slightly speed up loading them). + + @param domain + The name of the gettext catalog to search for + translatable strings. By default all loaded catalogs will be + searched. This provides a way to allow the strings to only come + from a specific catalog. + */ + wxXmlResource(const wxString& filemask, + int flags = wxXRC_USE_LOCALE, + const wxString domain = wxEmptyString); + wxXmlResource(int flags = wxXRC_USE_LOCALE, + const wxString domain = wxEmptyString); + //@} + + /** + Destructor. + */ + ~wxXmlResource(); + + /** + Initializes only a specific handler (or custom handler). Convention says + that the handler name is equal to the control's name plus 'XmlHandler', for + example + wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource compiler + (wxxrc) can create include file that contains initialization code for + all controls used within the resource. Note that this handler should be + allocated on the heap, since it will be delete by + ClearHandlers() later. + */ + void AddHandler(wxXmlResourceHandler* handler); + + /** + Attaches an unknown control to the given panel/window/dialog. + Unknown controls are used in conjunction with object class="unknown". + */ + bool AttachUnknownControl(const wxString& name, + wxWindow* control, + wxWindow* parent = @NULL); + + /** + Removes all handlers and deletes them (this means that any handlers added using + AddHandler() must be allocated on the heap). + */ + void ClearHandlers(); + + /** + Compares the XRC version to the argument. Returns -1 if the XRC version + is less than the argument, +1 if greater, and 0 if they equal. + */ + int CompareVersion(int major, int minor, int release, + int revision); + + /** + Gets the global resources object or creates one if none exists. + */ +#define wxXmlResource* Get() /* implementation is private */ + + /** + Returns the domain (message catalog) that will be used to load + translatable strings in the XRC. + */ + wxChar* GetDomain(); + + /** + Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and + wxXRC_NO_SUBCLASSING. + */ + int GetFlags(); + + /** + Returns version information (a.b.c.d = d+ 256*c + 256@c 2*b + 256@c 3*a). + */ + long GetVersion(); + + /** + Returns a numeric ID that is equivalent to the string ID used in an XML + resource. If an unknown @e str_id is requested (i.e. other than wxID_XXX + or integer), a new record is created which associates the given string with + a number. If @e value_if_not_found is @c wxID_NONE, the number is obtained via + wxNewId. Otherwise @e value_if_not_found is used. + Macro @c XRCID(name) is provided for convenient use in event tables. + */ +#define int GetXRCID(const wxString& str_id, int value_if_not_found = -2) /* implementation is private */ + + /** + Initializes handlers for all supported controls/windows. This will + make the executable quite big because it forces linking against + most of the wxWidgets library. + */ + void InitAllHandlers(); + + /** + Loads resources from XML files that match given filemask. + This method understands VFS (see filesys.h). + */ + bool Load(const wxString& filemask); + + /** + Loads a bitmap resource from a file. + */ + wxBitmap LoadBitmap(const wxString& name); + + //@{ + /** + Loads a dialog. @e dlg points to parent window (if any). + + This form is used to finish creation of an already existing instance (the main + reason + for this is that you may want to use derived class with a new event table). + + Example: + */ + wxDialog* LoadDialog(wxWindow* parent, const wxString& name); + bool LoadDialog(wxDialog* dlg, wxWindow* parent, + const wxString& name); + //@} + + /** + Loads a frame. + */ + bool LoadFrame(wxFrame* frame, wxWindow* parent, + const wxString& name); + + /** + Loads an icon resource from a file. + */ + wxIcon LoadIcon(const wxString& name); + + /** + Loads menu from resource. Returns @NULL on failure. + */ + wxMenu* LoadMenu(const wxString& name); + + //@{ + /** + Loads a menubar from resource. Returns @NULL on failure. + */ + wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name); + wxMenuBar* LoadMenuBar(const wxString& name); + //@} + + //@{ + /** + Load an object from the resource specifying both the resource name and the + class name. + + The first overload lets you load nonstandard container windows and returns @c + @NULL + on failure. The second one lets you finish the creation of an existing + instance and returns @false on failure. + */ + wxObject* LoadObject(wxWindow* parent, const wxString& name, + const wxString& classname); + bool LoadObject(wxObject* instance, wxWindow* parent, + const wxString& name, + const wxString& classname); + //@} + + //@{ + /** + Loads a panel. @e panel points to parent window (if any). This form + is used to finish creation of an already existing instance. + */ + wxPanel* LoadPanel(wxWindow* parent, const wxString& name); + bool LoadPanel(wxPanel* panel, wxWindow* parent, + const wxString& name); + //@} + + /** + Loads a toolbar. + */ + wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name); + + /** + Sets the global resources object and returns a pointer to the previous one (may + be @NULL). + */ +#define wxXmlResource* Set(wxXmlResource* res) /* implementation is private */ + + /** + Sets the domain (message catalog) that will be used to load + translatable strings in the XRC. + */ + wxChar* SetDomain(const wxChar* domain); + + /** + Sets flags (bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING). + */ + void SetFlags(int flags); + + /** + This function unloads a resource previously loaded by + Load(). + + Returns @true if the resource was successfully unloaded and @false if it + hasn't + been found in the list of loaded resources. + */ + bool Unload(const wxString& filename); +}; + + +/** + @class wxXmlResourceHandler + @headerfile xmlres.h wx/xrc/xmlres.h + + wxXmlResourceHandler is an abstract base class for resource handlers + capable of creating a control from an XML node. + + See @ref overview_xrcoverview "XML-based resource system overview" for details. + + @library{wxxrc} + @category{xrc} +*/ +class wxXmlResourceHandler : public wxObject +{ +public: + /** + Default constructor. + */ + wxXmlResourceHandler(); + + /** + Destructor. + */ + ~wxXmlResourceHandler(); + + /** + Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags + understood by this handler. + */ + void AddStyle(const wxString& name, int value); + + /** + Add styles common to all wxWindow-derived classes. + */ + void AddWindowStyles(); + + /** + Returns @true if it understands this node and can create + a resource from it, @false otherwise. + */ + bool CanHandle(wxXmlNode* node); + + /** + Creates children. + */ + void CreateChildren(wxObject* parent, bool this_hnd_only = @false); + + /** + Helper function. + */ + void CreateChildrenPrivately(wxObject* parent, + wxXmlNode* rootnode = @NULL); + + /** + Creates a resource from a node. + */ + wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent, + wxObject* instance = @NULL); + + /** + Creates an object (menu, dialog, control, ...) from an XML node. + Should check for validity. @e parent is a higher-level object (usually window, + dialog or panel) + that is often necessary to create the resource. + If @b instance is non-@NULL it should not create a new instance via 'new' but + should rather use this one, and call its Create method. + */ + wxObject* CreateResource(wxXmlNode* node, wxObject* parent, + wxObject* instance); + + /** + Called from CreateResource after variables + were filled. + */ + wxObject* DoCreateResource(); + + /** + ) + + Creates a animation from the filename specified in @e param. + */ + wxAnimation GetAnimation(); + + /** + , @b wxSize@e size = wxDefaultSize) + + Gets a bitmap. + */ + wxBitmap GetBitmap(); + + /** + Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false). + */ + bool GetBool(const wxString& param, bool defaultv = @false); + + /** + Gets colour in HTML syntax (#RRGGBB). + */ + wxColour GetColour(const wxString& param, + const wxColour& default = wxNullColour); + + /** + Returns the current file system. + */ + wxFileSystem GetCurFileSystem(); + + /** + Gets a dimension (may be in dialog units). + */ + wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0); + + /** + ) + + Gets a font. + */ + wxFont GetFont(); + + /** + Returns the XRCID. + */ +#define int GetID() /* implementation is private */ + + /** + , @b wxSize@e size = wxDefaultSize) + + Returns an icon. + */ + wxIcon GetIcon(); + + /** + Gets the integer value from the parameter. + */ + long GetLong(const wxString& param, long defaultv = 0); + + /** + Returns the resource name. + */ + wxString GetName(); + + /** + Gets node content from wxXML_ENTITY_NODE. + */ + wxString GetNodeContent(wxXmlNode* node); + + /** + Finds the node or returns @NULL. + */ + wxXmlNode* GetParamNode(const wxString& param); + + /** + Finds the parameter value or returns the empty string. + */ + wxString GetParamValue(const wxString& param); + + /** + ) + + Gets the position (may be in dialog units). + */ + wxPoint GetPosition(); + + /** + ) + + Gets the size (may be in dialog units). + */ + wxSize GetSize(); + + /** + , @b int@e defaults = 0) + + Gets style flags from text in form "flag | flag2| flag3 |..." + Only understands flags added with AddStyle. + */ + int GetStyle(); + + /** + Gets text from param and does some conversions: + + replaces \n, \r, \t by respective characters (according to C syntax) + replaces @c $ by @c and @c $$ by @c $ (needed for @c _File to @c File + translation because of XML syntax) + calls wxGetTranslations (unless disabled in wxXmlResource) + */ + wxString GetText(const wxString& param); + + /** + Check to see if a parameter exists. + */ + bool HasParam(const wxString& param); + + /** + Convenience function. Returns @true if the node has a property class equal to + classname, + e.g. object class="wxDialog". + */ + bool IsOfClass(wxXmlNode* node, const wxString& classname); + + /** + Sets the parent resource. + */ + void SetParentResource(wxXmlResource* res); + + /** + Sets common window options. + */ + void SetupWindow(wxWindow* wnd); +}; diff --git a/interface/zipstrm.h b/interface/zipstrm.h new file mode 100644 index 0000000000..c521efe34d --- /dev/null +++ b/interface/zipstrm.h @@ -0,0 +1,459 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: zipstrm.h +// Purpose: documentation for wxZipNotifier class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxZipNotifier + @wxheader{zipstrm.h} + + If you need to know when a wxZipInputStream + updates a wxZipEntry, + you can create a notifier by deriving from this abstract base class, + overriding wxZipNotifier::OnEntryUpdated. + An instance of your notifier class can then be assigned to wxZipEntry + objects, using wxZipEntry::SetNotifier. + + Setting a notifier is not usually necessary. It is used to handle + certain cases when modifying an zip in a pipeline (i.e. between + non-seekable streams). + See '@ref overview_wxarcnoseek "Archives on non-seekable streams"'. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry, + wxZipInputStream, wxZipOutputStream +*/ +class wxZipNotifier +{ +public: + /** + Override this to receive notifications when + an wxZipEntry object changes. + */ + void OnEntryUpdated(wxZipEntry& entry); +}; + + +/** + @class wxZipEntry + @wxheader{zipstrm.h} + + Holds the meta-data for an entry in a zip. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarc "Archive formats such as zip", wxZipInputStream, + wxZipOutputStream, wxZipNotifier +*/ +class wxZipEntry : public wxArchiveEntry +{ +public: + //@{ + /** + Copy constructor. + */ + wxZipEntry(const wxString& name = wxEmptyString); + wxZipEntry(const wxZipEntry& entry); + //@} + + /** + Make a copy of this entry. + */ + wxZipEntry* Clone(); + + //@{ + /** + A short comment for this entry. + */ + wxString GetComment(); + void SetComment(const wxString& comment); + //@} + + //@{ + /** + The low 8 bits are always the DOS/Windows file attributes for this entry. + The values of these attributes are given in the + enumeration @c wxZipAttributes. + + The remaining bits can store platform specific permission bits or + attributes, and their meaning depends on the value + of @ref systemmadeby() SetSystemMadeBy. + If IsMadeByUnix() is @true then the + high 16 bits are unix mode bits. + + The following other accessors access these bits: + + @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly + + @ref wxArchiveEntry::isdir IsDir/SetIsDir + + @ref mode() Get/SetMode + */ + wxUint32 GetExternalAttributes(); + void SetExternalAttributes(wxUint32 attr); + //@} + + //@{ + /** + The extra field from the entry's central directory record. + + The extra field is used to store platform or application specific + data. See Pkware's document 'appnote.txt' for information on its format. + */ + const char* GetExtra(); + size_t GetExtraLen(); + void SetExtra(const char* extra, size_t len); + //@} + + //@{ + /** + The extra field from the entry's local record. + + The extra field is used to store platform or application specific + data. See Pkware's document 'appnote.txt' for information on its format. + */ + const char* GetLocalExtra(); + size_t GetLocalExtraLen(); + void SetLocalExtra(const char* extra, size_t len); + //@} + + //@{ + /** + The compression method. The enumeration @c wxZipMethod lists the + possible values. + + The default constructor sets this to wxZIP_METHOD_DEFAULT, + which allows wxZipOutputStream to + choose the method when writing the entry. + */ + int GetMethod(); + void SetMethod(int method); + //@} + + //@{ + /** + Sets the DOS attributes + in @ref externalattributes() GetExternalAttributes + to be consistent with the @c mode given. + + If IsMadeByUnix() is @true then also + stores @c mode in GetExternalAttributes(). + + Note that the default constructor + sets @ref systemmadeby() GetSystemMadeBy to + wxZIP_SYSTEM_MSDOS by default. So to be able to store unix + permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX). + */ + int GetMode(); + void SetMode(int mode); + //@} + + //@{ + /** + The originating file-system. The default constructor sets this to + wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be + able to store unix permissions using @ref mode() SetMode. + */ + int GetSystemMadeBy(); + void SetSystemMadeBy(int system); + //@} + + /** + The compressed size of this entry in bytes. + */ + off_t GetCompressedSize(); + + /** + CRC32 for this entry's data. + */ + wxUint32 GetCrc(); + + /** + Returns a combination of the bits flags in the enumeration @c wxZipFlags. + */ + int GetFlags(); + + //@{ + /** + A static member that translates a filename into the internal format used + within the archive. If the third parameter is provided, the bool pointed + to is set to indicate whether the name looks like a directory name + (i.e. has a trailing path separator). + + @sa @ref overview_wxarcbyname "Looking up an archive entry by name" + */ + wxString GetInternalName(); + wxString GetInternalName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE, + bool* pIsDir = @NULL); + //@} + + /** + Returns @true if @ref systemmadeby() GetSystemMadeBy + is a flavour of unix. + */ + bool IsMadeByUnix(); + + //@{ + /** + Indicates that this entry's data is text in an 8-bit encoding. + */ + bool IsText(); + void SetIsText(bool isText = @true); + //@} + + //@{ + /** + Sets the notifier for this entry. + Whenever the wxZipInputStream updates + this entry, it will then invoke the associated + notifier's wxZipNotifier::OnEntryUpdated + method. + + Setting a notifier is not usually necessary. It is used to handle + certain cases when modifying an zip in a pipeline (i.e. between + non-seekable streams). + + @sa @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier + */ + void SetNotifier(wxZipNotifier& notifier); + void UnsetNotifier(); + //@} + + /** + Assignment operator. + */ + wxZipEntry& operator operator=(const wxZipEntry& entry); +}; + + +/** + @class wxZipInputStream + @wxheader{zipstrm.h} + + Input stream for reading zip files. + + wxZipInputStream::GetNextEntry returns an + wxZipEntry object containing the meta-data + for the next entry in the zip (and gives away ownership). Reading from + the wxZipInputStream then returns the entry's data. Eof() becomes @true + after an attempt has been made to read past the end of the entry's data. + When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). + + Note that in general zip entries are not seekable, and + wxZipInputStream::SeekI() always returns wxInvalidOffset. + + @library{wxbase} + @category{streams} + + @seealso + @ref overview_wxarc "Archive formats such as zip", wxZipEntry, wxZipOutputStream +*/ +class wxZipInputStream : public wxArchiveInputStream +{ +public: + //@{ + /** + Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6). + + When this constructor is used, an emulation of seeking is + switched on for compatibility with previous versions. Note however, + that it is deprecated. + */ + wxZipInputStream(wxInputStream& stream, + wxMBConv& conv = wxConvLocal); + wxZipInputStream(wxInputStream* stream, + wxMBConv& conv = wxConvLocal); + wxZipInputStream(const wxString& archive, + const wxString& file); + //@} + + /** + Closes the current entry. On a non-seekable stream reads to the end of + the current entry first. + */ + bool CloseEntry(); + + /** + Returns the zip comment. + + This is stored at the end of the zip, therefore when reading a zip + from a non-seekable stream, it returns the empty string until the + end of the zip has been reached, i.e. when GetNextEntry() returns + @NULL. + */ + wxString GetComment(); + + /** + Closes the current entry if one is open, then reads the meta-data for + the next entry and returns it in a wxZipEntry + object, giving away ownership. The stream is then open and can be read. + */ + wxZipEntry* GetNextEntry(); + + /** + For a zip on a seekable stream returns the total number of entries in + the zip. For zips on non-seekable streams returns the number of entries + returned so far by GetNextEntry(). + */ + int GetTotalEntries(); + + /** + Closes the current entry if one is open, then opens the entry specified + by the @e entry object. + + @e entry should be from the same zip file, and the zip should + be on a seekable stream. + */ + bool OpenEntry(wxZipEntry& entry); +}; + + +/** + @class wxZipClassFactory + @wxheader{zipstrm.h} + + Class factory for the zip archive format. See the base class + for details. + + @library{wxbase} + @category{FIXME} + + @seealso + @ref overview_wxarc "Archive formats such as zip", @ref overview_wxarcgeneric + "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream +*/ +class wxZipClassFactory : public wxArchiveClassFactory +{ +public: + +}; + + +/** + @class wxZipOutputStream + @wxheader{zipstrm.h} + + Output stream for writing zip files. + + wxZipOutputStream::PutNextEntry is used to create + a new entry in the output zip, then the entry's data is written to the + wxZipOutputStream. Another call to PutNextEntry() closes the current + entry and begins the next. + + @library{wxbase} + @category{streams} + + @seealso + @ref overview_wxarc "Archive formats such as zip", wxZipEntry, wxZipInputStream +*/ +class wxZipOutputStream : public wxArchiveOutputStream +{ +public: + //@{ + /** + Constructor. @c level is the compression level to use. + It can be a value between 0 and 9 or -1 to use the default value + which currently is equivalent to 6. + + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + + In a Unicode build the third parameter @c conv is used to translate + the filename and comment fields to an 8-bit encoding. It has no effect on the + stream's data. + */ + wxZipOutputStream(wxOutputStream& stream, int level = -1, + wxMBConv& conv = wxConvLocal); + wxZipOutputStream(wxOutputStream* stream, int level = -1, + wxMBConv& conv = wxConvLocal); + //@} + + /** + The destructor calls Close() to finish + writing the zip if it has not been called already. + */ + ~wxZipOutputStream(); + + /** + Finishes writing the zip, returning @true if successful. + Called by the destructor if not called explicitly. + */ + bool Close(); + + /** + Close the current entry. It is called implicitly whenever another new + entry is created with CopyEntry() + or PutNextEntry(), or + when the zip is closed. + */ + bool CloseEntry(); + + /** + Transfers the zip comment from the wxZipInputStream + to this output stream. + */ + bool CopyArchiveMetaData(wxZipInputStream& inputStream); + + /** + Takes ownership of @c entry and uses it to create a new entry + in the zip. @c entry is then opened in @c inputStream and its contents + copied to this stream. + + CopyEntry() is much more efficient than transferring the data using + Read() and Write() since it will copy them without decompressing and + recompressing them. + + For zips on seekable streams, @c entry must be from the same zip file + as @c stream. For non-seekable streams, @c entry must also be the + last thing read from @c inputStream. + */ + bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream); + + //@{ + /** + Set the compression level that will be used the next time an entry is + created. It can be a value between 0 and 9 or -1 to use the default value + which currently is equivalent to 6. + */ + int GetLevel(); + void SetLevel(int level); + //@} + + /** + ) + + Create a new directory entry + (see wxArchiveEntry::IsDir) + with the given name and timestamp. + + PutNextEntry() can + also be used to create directory entries, by supplying a name with + a trailing path separator. + */ + bool PutNextDirEntry(const wxString& name); + + //@{ + /** + , @b off_t@e size = wxInvalidOffset) + + Create a new entry with the given name, timestamp and size. + */ + bool PutNextEntry(wxZipEntry* entry); + bool PutNextEntry(const wxString& name); + //@} + + /** + Sets a comment for the zip as a whole. It is written at the end of the + zip. + */ + void SetComment(const wxString& comment); +}; diff --git a/interface/zstream.h b/interface/zstream.h new file mode 100644 index 0000000000..b0a01c8d7a --- /dev/null +++ b/interface/zstream.h @@ -0,0 +1,114 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: zstream.h +// Purpose: documentation for wxZlibOutputStream class +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxZlibOutputStream + @wxheader{zstream.h} + + This stream compresses all data written to it. The compressed output can be + in zlib or gzip format. + Note that writing the gzip format requires zlib version 1.2.1 or greater + (the builtin version does support gzip format). + + The stream is not seekable, wxOutputStream::SeekO returns + @e wxInvalidOffset. + + @library{wxbase} + @category{streams} + + @seealso + wxOutputStream, wxZlibInputStream +*/ +class wxZlibOutputStream : public wxFilterOutputStream +{ +public: + //@{ + /** + Creates a new write-only compressed stream. @e level means level of + compression. It is number between 0 and 9 (including these values) where + 0 means no compression and 9 best but slowest compression. -1 is default + value (currently equivalent to 6). + + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + + The @e flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the output data + will be in zlib or gzip format. wxZLIB_ZLIB is the default. + + If @e flags is wxZLIB_NO_HEADER, then a raw deflate stream is output + without either zlib or gzip headers. This is a lower level + mode, which is not usually used directly. It can be used to embed a raw + deflate stream in a higher level protocol. + + The following symbols can be use for the compression level and flags: + */ + wxZlibOutputStream(wxOutputStream& stream, int level = -1, + int flags = wxZLIB_ZLIB); + wxZlibOutputStream(wxOutputStream* stream, int level = -1, + int flags = wxZLIB_ZLIB); + //@} + + /** + Returns @true if zlib library in use can handle gzip compressed data. + */ + static bool CanHandleGZip(); +}; + + +/** + @class wxZlibInputStream + @wxheader{zstream.h} + + This filter stream decompresses a stream that is in zlib or gzip format. + Note that reading the gzip format requires zlib version 1.2.1 or greater, + (the builtin version does support gzip format). + + The stream is not seekable, wxInputStream::SeekI returns + @e wxInvalidOffset. Also wxStreamBase::GetSize is + not supported, it always returns 0. + + @library{wxbase} + @category{streams} + + @seealso + wxInputStream, wxZlibOutputStream. +*/ +class wxZlibInputStream : public wxFilterInputStream +{ +public: + //@{ + /** + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + + The @e flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the input data + is in zlib or gzip format. If wxZLIB_AUTO is used, then zlib will + autodetect the stream type, this is the default. + + If @e flags is wxZLIB_NO_HEADER, then the data is assumed to be a raw + deflate stream without either zlib or gzip headers. This is a lower level + mode, which is not usually used directly. It can be used to read a raw + deflate stream embedded in a higher level protocol. + + This version is not by default compatible with the output produced by + the version of @e wxZlibOutputStream in wxWidgets 2.4.x. However, + there is a compatibility mode, which is switched on by passing + wxZLIB_24COMPATIBLE for flags. Note that in when operating in compatibility + mode error checking is very much reduced. + The following symbols can be use for the flags: + */ + wxZlibInputStream(wxInputStream& stream, int flags = wxZLIB_AUTO); + wxZlibInputStream(wxInputStream* stream, + int flags = wxZLIB_AUTO); + //@} + + /** + Returns @true if zlib library in use can handle gzip compressed data. + */ + static bool CanHandleGZip(); +}; -- 2.45.2