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