interface/wx/pickerbase.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        pickerbase.h
   3 // Purpose:     interface of wxPickerBase
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxPickerBase
  11
  12     Base abstract class for all pickers which support an auxiliary text control.
  13
  14     This class handles all positioning and sizing of the text control like a
  15     an horizontal wxBoxSizer would do, with the text control on the left of the
  16     picker button.
  17
  18     The proportion (see wxSizer documentation for more info about proportion values)
  19     of the picker control defaults to 1 when there isn't a text control associated
  20     (see @c wxPB_USE_TEXTCTRL style) and to 0 otherwise.
  21
  22     @beginStyleTable
  23     @style{wxPB_USE_TEXTCTRL}
  24            Creates a text control to the left of the picker which is
  25            completely managed by this wxPickerBase class.
  26     @endStyleTable
  27
  28     @library{wxcore}
  29     @category{pickers}
  30
  31     @see wxColourPickerCtrl
  32 */
  33 class wxPickerBase : public wxControl
  34 {
  35 public:
  36     /**
  37         Returns the margin (in pixel) between the picker and the text control.
  38
  39         This function can be used only when HasTextCtrl() returns @true.
  40     */
  41     int GetInternalMargin() const;
  42
  43     /**
  44         Returns the proportion value of the picker.
  45     */
  46     int GetPickerCtrlProportion() const;
  47
  48     /**
  49         Returns a pointer to the text control handled by this window or @NULL if the
  50         @c wxPB_USE_TEXTCTRL style was not specified when this control was created.
  51
  52         @remarks
  53         The contents of the text control could be an invalid representation of
  54         the entity which can be chosen through the picker
  55         (e.g. when the user enters an invalid colour syntax because of a typo).
  56         Thus you should never parse the content of the textctrl to get the
  57         user's input; rather use the derived-class getter
  58         (e.g. wxColourPickerCtrl::GetColour(), wxFilePickerCtrl::GetPath(), etc).
  59     */
  60     wxTextCtrl* GetTextCtrl();
  61
  62     /**
  63         Returns the native implementation of the real picker control.
  64
  65         @note
  66         The returned control in the generic implementation of wxFilePickerCtrl,
  67         wxDirPickerCtrl, wxFontPickerCtrl and wxColourPickerCtrl is a specialized
  68         wxButton class so that you can change its label doing, e.g.:
  69         @code
  70             #ifdef __WXMSW__
  71                 // wxMSW is one of the platforms where the generic implementation
  72                 // of wxFilePickerCtrl is used...
  73
  74                 wxButton *pButt = wx_static_cast(wxButton*, myFilePickerCtrl->GetPickerCtrl());
  75                 if (pButt)
  76                     pButt->SetLabel("Custom browse string");
  77             #endif
  78         @endcode
  79     */
  80     wxControl* GetPickerCtrl();
  81
  82     /**
  83         Returns the proportion value of the text control.
  84
  85         This function can be used only when HasTextCtrl() returns @true.
  86     */
  87     int GetTextCtrlProportion() const;
  88
  89     /**
  90         Returns @true if this window has a valid text control (i.e. if the @c
  91         wxPB_USE_TEXTCTRL style was given when creating this control).
  92     */
  93     bool HasTextCtrl() const;
  94
  95     /**
  96         Returns @true if the picker control is growable.
  97     */
  98     bool IsPickerCtrlGrowable() const;
  99
 100     /**
 101         Returns @true if the text control is growable.
 102
 103         This function can be used only when HasTextCtrl() returns @true.
 104     */
 105     bool IsTextCtrlGrowable() const;
 106
 107     /**
 108         Sets the margin (in pixel) between the picker and the text control.
 109
 110         This function can be used only when HasTextCtrl() returns @true.
 111     */
 112     void SetInternalMargin(int margin);
 113
 114     /**
 115         Sets the picker control as growable when @c grow is @true.
 116     */
 117     void SetPickerCtrlGrowable(bool grow = true);
 118
 119     /**
 120         Sets the proportion value of the picker.
 121
 122         Look at the detailed description of wxPickerBase for more info.
 123     */
 124     void SetPickerCtrlProportion(int prop);
 125
 126     /**
 127         Sets the text control as growable when @c grow is @true.
 128
 129         This function can be used only when HasTextCtrl() returns @true.
 130     */
 131     void SetTextCtrlGrowable(bool grow = true);
 132
 133     /**
 134         Sets the proportion value of the text control.
 135
 136         Look at the detailed description of wxPickerBase for more info.
 137
 138         This function can be used only when HasTextCtrl() returns @true.
 139     */
 140     void SetTextCtrlProportion(int prop);
 141 };
 142