contrib/docs/latex/deprecated/function.tex

   1 \chapter{Functions}\label{functions}
   2 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
   3 \setfooter{\thepage}{}{}{}{}{\thepage}
   4
   5 Deprecated functions and macros defined in wxWindows are described here: you can
   6 either look up a function using the alphabetical listing of them or find it in
   7 the corresponding topic.
   8
   9 \section{Alphabetical functions and macros list}
  10
  11 %\helpref{wxGetResource}{wxgetresource}\\
  12 %\helpref{wxLoadUserResource}{wxloaduserresource}\\
  13 %\helpref{wxMakeMetafilePlaceable}{wxmakemetafileplaceable}\\
  14 %\helpref{wxNewId}{wxnewid}\\
  15 \helpref{wxLoadFromResource}{wxloadfromresource}\\
  16 \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}\\
  17 \helpref{wxResourceClear}{wxresourceclear}\\
  18 \helpref{wxResourceCreateBitmap}{wxresourcecreatebitmap}\\
  19 \helpref{wxResourceCreateIcon}{wxresourcecreateicon}\\
  20 \helpref{wxResourceCreateMenuBar}{wxresourcecreatemenubar}\\
  21 \helpref{wxResourceGetIdentifier}{wxresourcegetidentifier}\\
  22 \helpref{wxResourceParseData}{wxresourcedata}\\
  23 \helpref{wxResourceParseFile}{wxresourceparsefile}\\
  24 \helpref{wxResourceParseString}{wxresourceparsestring}\\
  25 \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}\\
  26 \helpref{wxResourceRegisterIconData}{wxresourceregistericondata}\\
  27 %\helpref{wxSetPrinterCommand}{wxsetprintercommand}\\
  28 %\helpref{wxSetPrinterFile}{wxsetprinterfile}\\
  29 %\helpref{wxSetPrinterMode}{wxsetprintermode}\\
  30 %\helpref{wxSetPrinterOptions}{wxsetprinteroptions}\\
  31 %\helpref{wxSetPrinterOrientation}{wxsetprinterorientation}\\
  32 %\helpref{wxSetPrinterPreviewCommand}{wxsetprinterpreviewcommand}\\
  33 %\helpref{wxSetPrinterScaling}{wxsetprinterscaling}\\
  34 %\helpref{wxSetPrinterTranslation}{wxsetprintertranslation}\\
  35
  36 \section{Printer settings}\label{printersettings}
  37
  38 {\bf NB:} These routines are obsolete and should no longer be used!
  39
  40 The following functions are used to control PostScript printing. Under
  41 Windows, PostScript output can only be sent to a file.
  42
  43 \wxheading{Include files}
  44
  45 <wx/dcps.h>
  46
  47 \membersection{::wxGetPrinterCommand}\label{wxgetprintercommand}
  48
  49 \func{wxString}{wxGetPrinterCommand}{\void}
  50
  51 Gets the printer command used to print a file. The default is {\tt lpr}.
  52
  53 \membersection{::wxGetPrinterFile}\label{wxgetprinterfile}
  54
  55 \func{wxString}{wxGetPrinterFile}{\void}
  56
  57 Gets the PostScript output filename.
  58
  59 \membersection{::wxGetPrinterMode}\label{wxgetprintermode}
  60
  61 \func{int}{wxGetPrinterMode}{\void}
  62
  63 Gets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
  64 The default is PS\_PREVIEW.
  65
  66 \membersection{::wxGetPrinterOptions}\label{wxgetprinteroptions}
  67
  68 \func{wxString}{wxGetPrinterOptions}{\void}
  69
  70 Gets the additional options for the print command (e.g. specific printer). The default is nothing.
  71
  72 \membersection{::wxGetPrinterOrientation}\label{wxgetprinterorientation}
  73
  74 \func{int}{wxGetPrinterOrientation}{\void}
  75
  76 Gets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
  77
  78 \membersection{::wxGetPrinterPreviewCommand}\label{wxgetprinterpreviewcommand}
  79
  80 \func{wxString}{wxGetPrinterPreviewCommand}{\void}
  81
  82 Gets the command used to view a PostScript file. The default depends on the platform.
  83
  84 \membersection{::wxGetPrinterScaling}\label{wxgetprinterscaling}
  85
  86 \func{void}{wxGetPrinterScaling}{\param{float *}{x}, \param{float *}{y}}
  87
  88 Gets the scaling factor for PostScript output. The default is 1.0, 1.0.
  89
  90 \membersection{::wxGetPrinterTranslation}\label{wxgetprintertranslation}
  91
  92 \func{void}{wxGetPrinterTranslation}{\param{float *}{x}, \param{float *}{y}}
  93
  94 Gets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
  95
  96 \membersection{::wxSetPrinterCommand}\label{wxsetprintercommand}
  97
  98 \func{void}{wxSetPrinterCommand}{\param{const wxString\& }{command}}
  99
 100 Sets the printer command used to print a file. The default is {\tt lpr}.
 101
 102 \membersection{::wxSetPrinterFile}\label{wxsetprinterfile}
 103
 104 \func{void}{wxSetPrinterFile}{\param{const wxString\& }{filename}}
 105
 106 Sets the PostScript output filename.
 107
 108 \membersection{::wxSetPrinterMode}\label{wxsetprintermode}
 109
 110 \func{void}{wxSetPrinterMode}{\param{int }{mode}}
 111
 112 Sets the printing mode controlling where output is sent (PS\_PREVIEW, PS\_FILE or PS\_PRINTER).
 113 The default is PS\_PREVIEW.
 114
 115 \membersection{::wxSetPrinterOptions}\label{wxsetprinteroptions}
 116
 117 \func{void}{wxSetPrinterOptions}{\param{const wxString\& }{options}}
 118
 119 Sets the additional options for the print command (e.g. specific printer). The default is nothing.
 120
 121 \membersection{::wxSetPrinterOrientation}\label{wxsetprinterorientation}
 122
 123 \func{void}{wxSetPrinterOrientation}{\param{int}{ orientation}}
 124
 125 Sets the orientation (PS\_PORTRAIT or PS\_LANDSCAPE). The default is PS\_PORTRAIT.
 126
 127 \membersection{::wxSetPrinterPreviewCommand}\label{wxsetprinterpreviewcommand}
 128
 129 \func{void}{wxSetPrinterPreviewCommand}{\param{const wxString\& }{command}}
 130
 131 Sets the command used to view a PostScript file. The default depends on the platform.
 132
 133 \membersection{::wxSetPrinterScaling}\label{wxsetprinterscaling}
 134
 135 \func{void}{wxSetPrinterScaling}{\param{float }{x}, \param{float }{y}}
 136
 137 Sets the scaling factor for PostScript output. The default is 1.0, 1.0.
 138
 139 \membersection{::wxSetPrinterTranslation}\label{wxsetprintertranslation}
 140
 141 \func{void}{wxSetPrinterTranslation}{\param{float }{x}, \param{float }{y}}
 142
 143 Sets the translation (from the top left corner) for PostScript output. The default is 0.0, 0.0.
 144
 145 \section{Resource functions}\label{resourcefunctions}
 146
 147 \overview{Resource functions}{resourceformats}
 148
 149 This section details functions for manipulating wxWindows (.WXR) resource
 150 files and loading user interface elements from resources.
 151
 152 \normalbox{Please note that this use of the word `resource' is different from that used when talking
 153 about initialisation file resource reading and writing, using such functions
 154 as wxWriteResource and wxGetResource. It is just an unfortunate clash of terminology.}
 155
 156 \helponly{For an overview of the wxWindows resource mechanism, see \helpref{the wxWindows resource system}{resourceformats}.}
 157
 158 See also \helpref{wxWindow::LoadFromResource}{wxwindowloadfromresource} for
 159 loading from resource data.
 160
 161 \membersection{wxLoadFromResource}\label{wxloadfromresource}
 162
 163 \func{virtual bool}{LoadFromResource}{\param{wxWindow* thisWindow}, \param{wxWindow* }{parent},\rtfsp
 164 \param{const wxString\& }{resourceName}, \param{const wxResourceTable* }{resourceTable = NULL}}
 165
 166 Loads a panel or dialog from a resource file.
 167
 168 \wxheading{Parameters}
 169
 170 \docparam{thisWindow}{Window to load the resource into.}
 171
 172 \docparam{parent}{Parent window.}
 173
 174 \docparam{resourceName}{The name of the resource to load.}
 175
 176 \docparam{resourceTable}{The resource table to load it from. If this is NULL, the
 177 default resource table will be used.}
 178
 179 \wxheading{Return value}
 180
 181 {\tt true} if the operation succeeded, otherwise {\tt false}.
 182
 183 \membersection{::wxResourceAddIdentifier}\label{wxresourceaddidentifier}
 184
 185 \func{bool}{wxResourceAddIdentifier}{\param{const wxString\& }{name}, \param{int }{value}}
 186
 187 Used for associating a name with an integer identifier (equivalent to dynamically\rtfsp
 188 {\tt\#}defining a name to an integer). Unlikely to be used by an application except
 189 perhaps for implementing resource functionality for interpreted languages.
 190
 191 \membersection{::wxResourceClear}\label{wxresourceclear}
 192
 193 \func{void}{wxResourceClear}{\void}
 194
 195 Clears the wxWindows resource table.
 196
 197 \membersection{::wxResourceCreateBitmap}\label{wxresourcecreatebitmap}
 198
 199 \func{wxBitmap *}{wxResourceCreateBitmap}{\param{const wxString\& }{resource}}
 200
 201 Creates a new bitmap from a file, static data, or Windows resource, given a valid
 202 wxWindows bitmap resource identifier. For example, if the .WXR file contains
 203 the following:
 204
 205 \begin{verbatim}
 206 static const wxString\& project_resource = "bitmap(name = 'project_resource',\
 207   bitmap = ['project', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
 208   bitmap = ['project.xpm', wxBITMAP_TYPE_XPM, 'X']).";
 209 \end{verbatim}
 210
 211 then this function can be called as follows:
 212
 213 \begin{verbatim}
 214   wxBitmap *bitmap  = wxResourceCreateBitmap("project_resource");
 215 \end{verbatim}
 216
 217 \membersection{::wxResourceCreateIcon}\label{wxresourcecreateicon}
 218
 219 \func{wxIcon *}{wxResourceCreateIcon}{\param{const wxString\& }{resource}}
 220
 221 Creates a new icon from a file, static data, or Windows resource, given a valid
 222 wxWindows icon resource identifier. For example, if the .WXR file contains
 223 the following:
 224
 225 \begin{verbatim}
 226 static const wxString\& project_resource = "icon(name = 'project_resource',\
 227   icon = ['project', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
 228   icon = ['project', wxBITMAP_TYPE_XBM_DATA, 'X']).";
 229 \end{verbatim}
 230
 231 then this function can be called as follows:
 232
 233 \begin{verbatim}
 234   wxIcon *icon = wxResourceCreateIcon("project_resource");
 235 \end{verbatim}
 236
 237 \membersection{::wxResourceCreateMenuBar}\label{wxresourcecreatemenubar}
 238
 239 \func{wxMenuBar *}{wxResourceCreateMenuBar}{\param{const wxString\& }{resource}}
 240
 241 Creates a new menu bar given a valid wxWindows menubar resource
 242 identifier. For example, if the .WXR file contains the following:
 243
 244 \begin{verbatim}
 245 static const wxString\& menuBar11 = "menu(name = 'menuBar11',\
 246   menu = \
 247   [\
 248     ['&File', 1, '', \
 249       ['&Open File', 2, 'Open a file'],\
 250       ['&Save File', 3, 'Save a file'],\
 251       [],\
 252       ['E&xit', 4, 'Exit program']\
 253     ],\
 254     ['&Help', 5, '', \
 255       ['&About', 6, 'About this program']\
 256     ]\
 257   ]).";
 258 \end{verbatim}
 259
 260 then this function can be called as follows:
 261
 262 \begin{verbatim}
 263   wxMenuBar *menuBar = wxResourceCreateMenuBar("menuBar11");
 264 \end{verbatim}
 265
 266
 267 \membersection{::wxResourceGetIdentifier}\label{wxresourcegetidentifier}
 268
 269 \func{int}{wxResourceGetIdentifier}{\param{const wxString\& }{name}}
 270
 271 Used for retrieving the integer value associated with an identifier.
 272 A zero value indicates that the identifier was not found.
 273
 274 See \helpref{wxResourceAddIdentifier}{wxresourceaddidentifier}.
 275
 276 \membersection{::wxResourceParseData}\label{wxresourcedata}
 277
 278 \func{bool}{wxResourceParseData}{\param{const wxString\& }{resource}, \param{wxResourceTable *}{table = NULL}}
 279
 280 Parses a string containing one or more wxWindows resource objects. If
 281 the resource objects are global static data that are included into the
 282 C++ program, then this function must be called for each variable
 283 containing the resource data, to make it known to wxWindows.
 284
 285 {\it resource} should contain data in the following form:
 286
 287 \begin{verbatim}
 288 dialog(name = 'dialog1',
 289   style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
 290   title = 'Test dialog box',
 291   x = 312, y = 234, width = 400, height = 300,
 292   modal = 0,
 293   control = [1000, wxStaticBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
 294       [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
 295   control = [1001, wxTextCtrl, '', 'wxTE_MULTILINE', 'text3',
 296       156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
 297       [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
 298       [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
 299 \end{verbatim}
 300
 301 This function will typically be used after including a {\tt .wxr} file into
 302 a C++ program as follows:
 303
 304 \begin{verbatim}
 305 #include "dialog1.wxr"
 306 \end{verbatim}
 307
 308 Each of the contained resources will declare a new C++ variable, and each
 309 of these variables should be passed to wxResourceParseData.
 310
 311 \membersection{::wxResourceParseFile}\label{wxresourceparsefile}
 312
 313 \func{bool}{wxResourceParseFile}{\param{const wxString\& }{filename}, \param{wxResourceTable *}{table = NULL}}
 314
 315 Parses a file containing one or more wxWindows resource objects
 316 in C++-compatible syntax. Use this function to dynamically load
 317 wxWindows resource data.
 318
 319 \membersection{::wxResourceParseString}\label{wxresourceparsestring}
 320
 321 \func{bool}{wxResourceParseString}{\param{char *}{s}, \param{wxResourceTable *}{table = NULL}}
 322
 323 Parses a string containing one or more wxWindows resource objects. If
 324 the resource objects are global static data that are included into the
 325 C++ program, then this function must be called for each variable
 326 containing the resource data, to make it known to wxWindows.
 327
 328 {\it resource} should contain data with the following form:
 329
 330 \begin{verbatim}
 331 dialog(name = 'dialog1',
 332   style = 'wxCAPTION | wxDEFAULT_DIALOG_STYLE',
 333   title = 'Test dialog box',
 334   x = 312, y = 234, width = 400, height = 300,
 335   modal = 0,
 336   control = [1000, wxStaticBox, 'Groupbox', '0', 'group6', 5, 4, 380, 262,
 337       [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]],
 338   control = [1001, wxTextCtrl, '', 'wxTE_MULTILINE', 'text3',
 339       156, 126, 200, 70, 'wxWindows is a multi-platform, GUI toolkit.',
 340       [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],
 341       [11, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0]]).
 342 \end{verbatim}
 343
 344 This function will typically be used after calling \helpref{wxLoadUserResource}{wxloaduserresource} to
 345 load an entire {\tt .wxr file} into a string.
 346
 347 \membersection{::wxResourceRegisterBitmapData}\label{registerbitmapdata}
 348
 349 \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char *}{xbm\_data}, \param{int }{width},
 350 \param{int }{height}, \param{wxResourceTable *}{table = NULL}}
 351
 352 \func{bool}{wxResourceRegisterBitmapData}{\param{const wxString\& }{name}, \param{char **}{xpm\_data}}
 353
 354 Makes {\tt\#}included XBM or XPM bitmap data known to the wxWindows resource system.
 355 This is required if other resources will use the bitmap data, since otherwise there
 356 is no connection between names used in resources, and the global bitmap data.
 357
 358 \membersection{::wxResourceRegisterIconData}\label{wxresourceregistericondata}
 359
 360 Another name for \helpref{wxResourceRegisterBitmapData}{registerbitmapdata}.
 361