interface/wx/defs.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/defs.h
   3 // Purpose:     interface of global functions
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     No id matches this one when compared to it.
  12 */
  13 int wxID_NONE = -3;
  14
  15 /**
  16     Id for a separator line in the menu (invalid for normal item).
  17 */
  18 int wxID_SEPARATOR = -2;
  19
  20 /**
  21     Any id: means that we don't care about the id, whether when installing
  22     an event handler or when creating a new window.
  23 */
  24 int wxID_ANY = -1;
  25
  26 /**
  27     Item kinds for use with wxMenu, wxMenuItem, and wxToolBar.
  28
  29     @see wxMenu::Append(), wxMenuItem::wxMenuItem(), wxToolBar::AddTool()
  30 */
  31 enum wxItemKind
  32 {
  33     wxITEM_SEPARATOR = -1,
  34
  35     /**
  36         Normal tool button / menu item.
  37
  38         @see wxToolBar::AddTool(), wxMenu::AppendItem().
  39     */
  40     wxITEM_NORMAL,
  41
  42     /**
  43         Check (or toggle) tool button / menu item.
  44
  45         @see wxToolBar::AddCheckTool(), wxMenu::AppendCheckItem().
  46     */
  47     wxITEM_CHECK,
  48
  49     /**
  50         Radio tool button / menu item.
  51
  52         @see wxToolBar::AddRadioTool(), wxMenu::AppendRadioItem().
  53     */
  54     wxITEM_RADIO,
  55
  56     /**
  57         Normal tool button with a dropdown arrow next to it. Clicking the
  58         dropdown arrow sends a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event and may
  59         also display the menu previously associated with the item with
  60         wxToolBar::SetDropdownMenu(). Currently this type of tools is supported
  61         under MSW and GTK.
  62     */
  63     wxITEM_DROPDOWN,
  64
  65     wxITEM_MAX
  66 };
  67
  68
  69 /**
  70     Paper size types for use with the printing framework.
  71
  72     @see overview_printing, wxPrintData::SetPaperId()
  73 */
  74 enum wxPaperSize
  75 {
  76     wxPAPER_NONE,               ///<  Use specific dimensions
  77     wxPAPER_LETTER,             ///<  Letter, 8 1/2 by 11 inches
  78     wxPAPER_LEGAL,              ///<  Legal, 8 1/2 by 14 inches
  79     wxPAPER_A4,                 ///<  A4 Sheet, 210 by 297 millimeters
  80     wxPAPER_CSHEET,             ///<  C Sheet, 17 by 22 inches
  81     wxPAPER_DSHEET,             ///<  D Sheet, 22 by 34 inches
  82     wxPAPER_ESHEET,             ///<  E Sheet, 34 by 44 inches
  83     wxPAPER_LETTERSMALL,        ///<  Letter Small, 8 1/2 by 11 inches
  84     wxPAPER_TABLOID,            ///<  Tabloid, 11 by 17 inches
  85     wxPAPER_LEDGER,             ///<  Ledger, 17 by 11 inches
  86     wxPAPER_STATEMENT,          ///<  Statement, 5 1/2 by 8 1/2 inches
  87     wxPAPER_EXECUTIVE,          ///<  Executive, 7 1/4 by 10 1/2 inches
  88     wxPAPER_A3,                 ///<  A3 sheet, 297 by 420 millimeters
  89     wxPAPER_A4SMALL,            ///<  A4 small sheet, 210 by 297 millimeters
  90     wxPAPER_A5,                 ///<  A5 sheet, 148 by 210 millimeters
  91     wxPAPER_B4,                 ///<  B4 sheet, 250 by 354 millimeters
  92     wxPAPER_B5,                 ///<  B5 sheet, 182-by-257-millimeter paper
  93     wxPAPER_FOLIO,              ///<  Folio, 8-1/2-by-13-inch paper
  94     wxPAPER_QUARTO,             ///<  Quarto, 215-by-275-millimeter paper
  95     wxPAPER_10X14,              ///<  10-by-14-inch sheet
  96     wxPAPER_11X17,              ///<  11-by-17-inch sheet
  97     wxPAPER_NOTE,               ///<  Note, 8 1/2 by 11 inches
  98     wxPAPER_ENV_9,              ///<  #9 Envelope, 3 7/8 by 8 7/8 inches
  99     wxPAPER_ENV_10,             ///<  #10 Envelope, 4 1/8 by 9 1/2 inches
 100     wxPAPER_ENV_11,             ///<  #11 Envelope, 4 1/2 by 10 3/8 inches
 101     wxPAPER_ENV_12,             ///<  #12 Envelope, 4 3/4 by 11 inches
 102     wxPAPER_ENV_14,             ///<  #14 Envelope, 5 by 11 1/2 inches
 103     wxPAPER_ENV_DL,             ///<  DL Envelope, 110 by 220 millimeters
 104     wxPAPER_ENV_C5,             ///<  C5 Envelope, 162 by 229 millimeters
 105     wxPAPER_ENV_C3,             ///<  C3 Envelope, 324 by 458 millimeters
 106     wxPAPER_ENV_C4,             ///<  C4 Envelope, 229 by 324 millimeters
 107     wxPAPER_ENV_C6,             ///<  C6 Envelope, 114 by 162 millimeters
 108     wxPAPER_ENV_C65,            ///<  C65 Envelope, 114 by 229 millimeters
 109     wxPAPER_ENV_B4,             ///<  B4 Envelope, 250 by 353 millimeters
 110     wxPAPER_ENV_B5,             ///<  B5 Envelope, 176 by 250 millimeters
 111     wxPAPER_ENV_B6,             ///<  B6 Envelope, 176 by 125 millimeters
 112     wxPAPER_ENV_ITALY,          ///<  Italy Envelope, 110 by 230 millimeters
 113     wxPAPER_ENV_MONARCH,        ///<  Monarch Envelope, 3 7/8 by 7 1/2 inches
 114     wxPAPER_ENV_PERSONAL,       ///<  6 3/4 Envelope, 3 5/8 by 6 1/2 inches
 115     wxPAPER_FANFOLD_US,         ///<  US Std Fanfold, 14 7/8 by 11 inches
 116     wxPAPER_FANFOLD_STD_GERMAN, ///<  German Std Fanfold, 8 1/2 by 12 inches
 117     wxPAPER_FANFOLD_LGL_GERMAN, ///<  German Legal Fanfold, 8 1/2 by 13 inches
 118
 119     // wxMSW Only
 120
 121     wxPAPER_ISO_B4,             ///<  B4 (ISO) 250 x 353 mm
 122     wxPAPER_JAPANESE_POSTCARD,  ///<  Japanese Postcard 100 x 148 mm
 123     wxPAPER_9X11,               ///<  9 x 11 in
 124     wxPAPER_10X11,              ///<  10 x 11 in
 125     wxPAPER_15X11,              ///<  15 x 11 in
 126     wxPAPER_ENV_INVITE,         ///<  Envelope Invite 220 x 220 mm
 127     wxPAPER_LETTER_EXTRA,       ///<  Letter Extra 9.5 x 12 in
 128     wxPAPER_LEGAL_EXTRA,        ///<  Legal Extra 9.5 x 15 in
 129     wxPAPER_TABLOID_EXTRA,      ///<  Tabloid Extra 11.69 x 18 in
 130     wxPAPER_A4_EXTRA,           ///<  A4 Extra 9.27 x 12.69 in
 131     wxPAPER_LETTER_TRANSVERSE,  ///<  Letter Transverse 8.5 x 11 in
 132     wxPAPER_A4_TRANSVERSE,      ///<  A4 Transverse 210 x 297 mm
 133     wxPAPER_LETTER_EXTRA_TRANSVERSE, ///<  Letter Extra Transverse 9.5 x 12 in
 134     wxPAPER_A_PLUS,             ///<  SuperA/SuperA/A4 227 x 356 mm
 135     wxPAPER_B_PLUS,             ///<  SuperB/SuperB/A3 305 x 487 mm
 136     wxPAPER_LETTER_PLUS,        ///<  Letter Plus 8.5 x 12.69 in
 137     wxPAPER_A4_PLUS,            ///<  A4 Plus 210 x 330 mm
 138     wxPAPER_A5_TRANSVERSE,      ///<  A5 Transverse 148 x 210 mm
 139     wxPAPER_B5_TRANSVERSE,      ///<  B5 (JIS) Transverse 182 x 257 mm
 140     wxPAPER_A3_EXTRA,           ///<  A3 Extra 322 x 445 mm
 141     wxPAPER_A5_EXTRA,           ///<  A5 Extra 174 x 235 mm
 142     wxPAPER_B5_EXTRA,           ///<  B5 (ISO) Extra 201 x 276 mm
 143     wxPAPER_A2,                 ///<  A2 420 x 594 mm
 144     wxPAPER_A3_TRANSVERSE,      ///<  A3 Transverse 297 x 420 mm
 145     wxPAPER_A3_EXTRA_TRANSVERSE, ///<  A3 Extra Transverse 322 x 445 mm
 146
 147     wxPAPER_DBL_JAPANESE_POSTCARD, ///< Japanese Double Postcard 200 x 148 mm
 148     wxPAPER_A6,                 ///< A6 105 x 148 mm
 149     wxPAPER_JENV_KAKU2,         ///< Japanese Envelope Kaku #2
 150     wxPAPER_JENV_KAKU3,         ///< Japanese Envelope Kaku #3
 151     wxPAPER_JENV_CHOU3,         ///< Japanese Envelope Chou #3
 152     wxPAPER_JENV_CHOU4,         ///< Japanese Envelope Chou #4
 153     wxPAPER_LETTER_ROTATED,     ///< Letter Rotated 11 x 8 1/2 in
 154     wxPAPER_A3_ROTATED,         ///< A3 Rotated 420 x 297 mm
 155     wxPAPER_A4_ROTATED,         ///< A4 Rotated 297 x 210 mm
 156     wxPAPER_A5_ROTATED,         ///< A5 Rotated 210 x 148 mm
 157     wxPAPER_B4_JIS_ROTATED,     ///< B4 (JIS) Rotated 364 x 257 mm
 158     wxPAPER_B5_JIS_ROTATED,     ///< B5 (JIS) Rotated 257 x 182 mm
 159     wxPAPER_JAPANESE_POSTCARD_ROTATED, ///< Japanese Postcard Rotated 148 x 100 mm
 160     wxPAPER_DBL_JAPANESE_POSTCARD_ROTATED, ///< Double Japanese Postcard Rotated 148 x 200 mm
 161     wxPAPER_A6_ROTATED,         ///< A6 Rotated 148 x 105 mm
 162     wxPAPER_JENV_KAKU2_ROTATED, ///< Japanese Envelope Kaku #2 Rotated
 163     wxPAPER_JENV_KAKU3_ROTATED, ///< Japanese Envelope Kaku #3 Rotated
 164     wxPAPER_JENV_CHOU3_ROTATED, ///< Japanese Envelope Chou #3 Rotated
 165     wxPAPER_JENV_CHOU4_ROTATED, ///< Japanese Envelope Chou #4 Rotated
 166     wxPAPER_B6_JIS,             ///< B6 (JIS) 128 x 182 mm
 167     wxPAPER_B6_JIS_ROTATED,     ///< B6 (JIS) Rotated 182 x 128 mm
 168     wxPAPER_12X11,              ///< 12 x 11 in
 169     wxPAPER_JENV_YOU4,          ///< Japanese Envelope You #4
 170     wxPAPER_JENV_YOU4_ROTATED,  ///< Japanese Envelope You #4 Rotated
 171     wxPAPER_P16K,               ///< PRC 16K 146 x 215 mm
 172     wxPAPER_P32K,               ///< PRC 32K 97 x 151 mm
 173     wxPAPER_P32KBIG,            ///< PRC 32K(Big) 97 x 151 mm
 174     wxPAPER_PENV_1,             ///< PRC Envelope #1 102 x 165 mm
 175     wxPAPER_PENV_2,             ///< PRC Envelope #2 102 x 176 mm
 176     wxPAPER_PENV_3,             ///< PRC Envelope #3 125 x 176 mm
 177     wxPAPER_PENV_4,             ///< PRC Envelope #4 110 x 208 mm
 178     wxPAPER_PENV_5,             ///< PRC Envelope #5 110 x 220 mm
 179     wxPAPER_PENV_6,             ///< PRC Envelope #6 120 x 230 mm
 180     wxPAPER_PENV_7,             ///< PRC Envelope #7 160 x 230 mm
 181     wxPAPER_PENV_8,             ///< PRC Envelope #8 120 x 309 mm
 182     wxPAPER_PENV_9,             ///< PRC Envelope #9 229 x 324 mm
 183     wxPAPER_PENV_10,            ///< PRC Envelope #10 324 x 458 mm
 184     wxPAPER_P16K_ROTATED,       ///< PRC 16K Rotated
 185     wxPAPER_P32K_ROTATED,       ///< PRC 32K Rotated
 186     wxPAPER_P32KBIG_ROTATED,    ///< PRC 32K(Big) Rotated
 187     wxPAPER_PENV_1_ROTATED,     ///< PRC Envelope #1 Rotated 165 x 102 mm
 188     wxPAPER_PENV_2_ROTATED,     ///< PRC Envelope #2 Rotated 176 x 102 mm
 189     wxPAPER_PENV_3_ROTATED,     ///< PRC Envelope #3 Rotated 176 x 125 mm
 190     wxPAPER_PENV_4_ROTATED,     ///< PRC Envelope #4 Rotated 208 x 110 mm
 191     wxPAPER_PENV_5_ROTATED,     ///< PRC Envelope #5 Rotated 220 x 110 mm
 192     wxPAPER_PENV_6_ROTATED,     ///< PRC Envelope #6 Rotated 230 x 120 mm
 193     wxPAPER_PENV_7_ROTATED,     ///< PRC Envelope #7 Rotated 230 x 160 mm
 194     wxPAPER_PENV_8_ROTATED,     ///< PRC Envelope #8 Rotated 309 x 120 mm
 195     wxPAPER_PENV_9_ROTATED,     ///< PRC Envelope #9 Rotated 324 x 229 mm
 196     wxPAPER_PENV_10_ROTATED     ///< PRC Envelope #10 Rotated 458 x 324 m
 197 };
 198
 199
 200 /** @addtogroup group_funcmacro_byteorder */
 201 //@{
 202
 203 /**
 204     This macro will swap the bytes of the @a value variable from little endian
 205     to big endian or vice versa unconditionally, i.e. independently of the
 206     current platform.
 207
 208     @header{wx/defs.h}
 209 */
 210 #define wxINT32_SWAP_ALWAYS( wxInt32_value )
 211 #define wxUINT32_SWAP_ALWAYS( wxUint32_value )
 212 #define wxINT16_SWAP_ALWAYS( wxInt16_value )
 213 #define wxUINT16_SWAP_ALWAYS( wxUint16_value )
 214
 215 //@}
 216
 217 /** @addtogroup group_funcmacro_byteorder */
 218 //@{
 219
 220 /**
 221     This macro will swap the bytes of the @a value variable from little endian
 222     to big endian or vice versa if the program is compiled on a big-endian
 223     architecture (such as Sun work stations). If the program has been compiled
 224     on a little-endian architecture, the value will be unchanged.
 225
 226     Use these macros to read data from and write data to a file that stores
 227     data in little-endian (for example Intel i386) format.
 228
 229     @header{wx/defs.h}
 230 */
 231 #define wxINT32_SWAP_ON_BE( wxInt32_value )
 232 #define wxUINT32_SWAP_ON_BE( wxUint32_value )
 233 #define wxINT16_SWAP_ON_BE( wxInt16_value )
 234 #define wxUINT16_SWAP_ON_BE( wxUint16_value )
 235
 236 //@}
 237
 238 /** @addtogroup group_funcmacro_byteorder */
 239 //@{
 240
 241 /**
 242     This macro will swap the bytes of the @a value variable from little endian
 243     to big endian or vice versa if the program is compiled on a little-endian
 244     architecture (such as Intel PCs). If the program has been compiled on a
 245     big-endian architecture, the value will be unchanged.
 246
 247     Use these macros to read data from and write data to a file that stores
 248     data in big-endian format.
 249
 250     @header{wx/defs.h}
 251 */
 252 #define wxINT32_SWAP_ON_LE( wxInt32_value )
 253 #define wxUINT32_SWAP_ON_LE( wxUint32_value )
 254 #define wxINT16_SWAP_ON_LE( wxInt16_value )
 255 #define wxUINT16_SWAP_ON_LE( wxUint16_value )
 256
 257 //@}
 258
 259
 260
 261 /** @addtogroup group_funcmacro_misc */
 262 //@{
 263
 264 /**
 265     This macro can be used in a class declaration to disable the generation of
 266     default assignment operator.
 267
 268     Some classes have a well-defined copy constructor but cannot have an
 269     assignment operator, typically because they can't be modified once created.
 270     In such case, this macro can be used to disable the automatic assignment
 271     operator generation.
 272
 273     @see DECLARE_NO_COPY_CLASS()
 274  */
 275 #define DECLARE_NO_ASSIGN_CLASS(classname)
 276
 277 /**
 278     This macro can be used in a class declaration to disable the generation of
 279     default copy ctor and assignment operator.
 280
 281     Some classes don't have a well-defined copying semantics. In this case the
 282     standard C++ convention is to not allow copying them. One way of achieving
 283     it is to use this macro which simply defines a private copy constructor and
 284     assignment operator.
 285
 286     Beware that simply not defining copy constructor and assignment operator is
 287     @em not enough as the compiler would provide its own automatically-generated
 288     versions of them -- hence the usefulness of this macro.
 289
 290     Example of use:
 291     @code
 292     class FooWidget
 293     {
 294     public:
 295         FooWidget();
 296         ...
 297
 298     private:
 299         // widgets can't be copied
 300         DECLARE_NO_COPY_CLASS(FooWidget)
 301     };
 302     @endcode
 303
 304     Notice that a semicolon should not be used after this macro and that it
 305     changes the access specifier to private internally so it is better to use
 306     it at the end of the class declaration.
 307  */
 308 #define DECLARE_NO_COPY_CLASS(classname)
 309
 310 /**
 311     Equivalent of DECLARE_NO_COPY_CLASS() for template classes.
 312
 313     This macro can be used for template classes (with a single template
 314     parameter) for the same purpose as DECLARE_NO_COPY_CLASS() is used with the
 315     non-template classes.
 316
 317     @param classname The name of the template class.
 318     @param arg The name of the template parameter.
 319  */
 320 #define DECLARE_NO_COPY_TEMPLATE_CLASS(classname, arg)
 321
 322 /**
 323     A function which deletes and nulls the pointer.
 324
 325     This function uses operator delete to free the pointer and also sets it to
 326     @NULL. Notice that this does @em not work for arrays, use wxDELETEA() for
 327     them.
 328
 329     @code
 330         MyClass *ptr = new MyClass;
 331         ...
 332         wxDELETE(ptr);
 333         wxASSERT(!ptr);
 334     @endcode
 335
 336     @header{wx/defs.h}
 337 */
 338 template <typename T> wxDELETE(T*& ptr);
 339
 340 /**
 341     A function which deletes and nulls the pointer.
 342
 343     This function uses vector operator delete (@c delete[]) to free the array
 344     pointer and also sets it to @NULL. Notice that this does @em not work for
 345     non-array pointers, use wxDELETE() for them.
 346
 347     @code
 348         MyClass *array = new MyClass[17];
 349         ...
 350         wxDELETEA(array);
 351         wxASSERT(!array);
 352     @endcode
 353
 354     @see wxDELETE()
 355
 356     @header{wx/defs.h}
 357 */
 358 template <typename T> wxDELETEA(T*& array);
 359
 360 /**
 361     This macro can be used around a function declaration to generate warnings
 362     indicating that this function is deprecated (i.e. obsolete and planned to
 363     be removed in the future) when it is used. Only Visual C++ 7 and higher and
 364     g++ compilers currently support this functionality.
 365
 366     Example of use:
 367
 368     @code
 369     // old function, use wxString version instead
 370     wxDEPRECATED( void wxGetSomething(char *buf, size_t len) );
 371
 372     // ...
 373     wxString wxGetSomething();
 374     @endcode
 375
 376     @header{wx/defs.h}
 377 */
 378 #define wxDEPRECATED(function)
 379
 380 /**
 381     This is a special version of wxDEPRECATED() macro which only does something
 382     when the deprecated function is used from the code outside wxWidgets itself
 383     but doesn't generate warnings when it is used from wxWidgets.
 384
 385     It is used with the virtual functions which are called by the library
 386     itself -- even if such function is deprecated the library still has to call
 387     it to ensure that the existing code overriding it continues to work, but
 388     the use of this macro ensures that a deprecation warning will be generated
 389     if this function is used from the user code or, in case of Visual C++, even
 390     when it is simply overridden.
 391
 392     @header{wx/defs.h}
 393 */
 394 #define wxDEPRECATED_BUT_USED_INTERNALLY(function)
 395
 396 /**
 397     This macro is similar to wxDEPRECATED() but can be used to not only declare
 398     the function @a function as deprecated but to also provide its (inline)
 399     implementation @a body.
 400
 401     It can be used as following:
 402
 403     @code
 404     class wxFoo
 405     {
 406     public:
 407         // OldMethod() is deprecated, use NewMethod() instead
 408         void NewMethod();
 409         wxDEPRECATED_INLINE( void OldMethod(), NewMethod() );
 410     };
 411     @endcode
 412
 413     @header{wx/defs.h}
 414 */
 415 #define wxDEPRECATED_INLINE(func, body)
 416
 417 /**
 418     @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if
 419     the compiler supports it or nothing otherwise. Thus, it can be used even in
 420     the code which might have to be compiled with an old compiler without
 421     support for this language feature but still take advantage of it when it is
 422     available.
 423
 424     @header{wx/defs.h}
 425 */
 426 #define wxEXPLICIT
 427
 428 /**
 429     GNU C++ compiler gives a warning for any class whose destructor is private
 430     unless it has a friend. This warning may sometimes be useful but it doesn't
 431     make sense for reference counted class which always delete themselves
 432     (hence destructor should be private) but don't necessarily have any
 433     friends, so this macro is provided to disable the warning in such case. The
 434     @a name parameter should be the name of the class but is only used to
 435     construct a unique friend class name internally.
 436
 437     Example of using the macro:
 438
 439     @code
 440     class RefCounted
 441     {
 442     public:
 443         RefCounted() { m_nRef = 1; }
 444         void IncRef() { m_nRef++ ; }
 445         void DecRef() { if ( !--m_nRef ) delete this; }
 446
 447     private:
 448         ~RefCounted() { }
 449
 450         wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted)
 451     };
 452     @endcode
 453
 454     Notice that there should be no semicolon after this macro.
 455
 456     @header{wx/defs.h}
 457 */
 458 #define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name)
 459
 460 /**
 461     Swaps the contents of two variables.
 462
 463     This is similar to std::swap() but can be used even on the platforms where
 464     the standard C++ library is not available (if you don't target such
 465     platforms, please use std::swap() instead).
 466
 467     The function relies on type T being copy constructible and assignable.
 468
 469     Example of use:
 470     @code
 471         int x = 3,
 472             y = 4;
 473         wxSwap(x, y);
 474         wxASSERT( x == 4 && y == 3 );
 475     @endcode
 476  */
 477 template <typename T> wxSwap(T& first, T& second);
 478
 479 /**
 480     This macro is the same as the standard C99 @c va_copy for the compilers
 481     which support it or its replacement for those that don't. It must be used
 482     to preserve the value of a @c va_list object if you need to use it after
 483     passing it to another function because it can be modified by the latter.
 484
 485     As with @c va_start, each call to @c wxVaCopy must have a matching
 486     @c va_end.
 487
 488     @header{wx/defs.h}
 489 */
 490 void wxVaCopy(va_list argptrDst, va_list argptrSrc);
 491
 492 //@}
 493
 494