interface/wx/propgrid/editors.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        editors.h
   3 // Purpose:     interface of wxPropertyGrid editors
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxPGEditor
  12
  13     Base class for custom wxPropertyGrid editors.
  14
  15     @remarks
  16     - Names of built-in property editors are: TextCtrl, Choice,
  17       ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional
  18       editors include SpinCtrl and DatePickerCtrl, but using them requires
  19       calling wxPropertyGrid::RegisterAdditionalEditors() prior use.
  20
  21     - Pointer to built-in editor is available as wxPGEditor_EditorName
  22       (eg. wxPGEditor_TextCtrl).
  23
  24     - Before you start using new editor you just created, you need to register
  25       it using static function
  26       wxPropertyGrid::RegisterEditorClass(), with code like this:
  27         @code
  28             wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");
  29         @endcode
  30       After that, wxPropertyGrid will take ownership of the given object, but
  31       you should still store editorPointer somewhere, so you can pass it to
  32       wxPGProperty::SetEditor(), or return it from wxPGEditor::DoGetEditorClass().
  33
  34     @library{wxpropgrid}
  35     @category{propgrid}
  36 */
  37 class wxPGEditor : public wxObject
  38 {
  39 public:
  40
  41     /** Constructor. */
  42     wxPGEditor();
  43
  44     /** Destructor. */
  45     virtual ~wxPGEditor();
  46
  47     /**
  48         Returns pointer to the name of the editor. For example,
  49         wxPGEditor_TextCtrl has name "TextCtrl". If you dont' need to access
  50         your custom editor by string name, then you do not need to implement
  51         this function.
  52     */
  53     virtual wxString GetName() const;
  54
  55     /**
  56         Instantiates editor controls.
  57
  58         @param propgrid
  59             wxPropertyGrid to which the property belongs (use as parent for control).
  60
  61         @param property
  62             Property for which this method is called.
  63
  64         @param pos
  65             Position, inside wxPropertyGrid, to create control(s) to.
  66
  67         @param size
  68             Initial size for control(s).
  69
  70         @remarks
  71         - Primary control shall use id wxPG_SUBID1, and secondary (button) control
  72           shall use wxPG_SUBID2.
  73         - Implementation shoud connect all necessary events to the
  74           wxPropertyGrid::OnCustomEditorEvent(). For example:
  75             @code
  76                 control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
  77                                  wxEventHandler(wxPropertyGrid::OnCustomEditorEvent),
  78                                  NULL, propgrid);
  79             @endcode
  80           OnCustomEditorEvent will then forward events, first to
  81           wxPGEditor::OnEvent() and then to wxPGProperty::OnEvent().
  82
  83         @see wxPropertyGrid::OnCustomEditorEvent(), wxEvtHandler::Connect()
  84     */
  85     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid,
  86                                            wxPGProperty* property,
  87                                            const wxPoint& pos,
  88                                            const wxSize& size ) const = 0;
  89
  90     /** Loads value from property to the control. */
  91     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
  92
  93     /**
  94         Draws value for given property.
  95     */
  96     virtual void DrawValue( wxDC& dc, const wxRect& rect,
  97                             wxPGProperty* property, const wxString& text ) const;
  98
  99     /**
 100         Handles events. Returns @true if value in control was modified
 101         (see wxPGProperty::OnEvent() for more information).
 102
 103         @remarks wxPropertyGrid will automatically unfocus the editor when
 104                  wxEVT_COMMAND_TEXT_ENTER is received and when it results in
 105                  property value being modified. This happens regardless of
 106                  editor type (ie. behavior is same for any wxTextCtrl and
 107                  wxComboBox based editor).
 108     */
 109     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 110         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 111
 112     /**
 113         Returns value from control, via parameter 'variant'.
 114         Usually ends up calling property's StringToValue() or IntToValue().
 115         Returns @true if value was different.
 116     */
 117     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,
 118                                       wxWindow* ctrl ) const;
 119
 120     /** Sets value in control to unspecified. */
 121     virtual void SetValueToUnspecified( wxPGProperty* property,
 122                                         wxWindow* ctrl ) const = 0;
 123
 124     /** Sets control's value specifically from string. */
 125     virtual void SetControlStringValue( wxPGProperty* property,
 126                                         wxWindow* ctrl, const wxString& txt ) const;
 127
 128     /** Sets control's value specifically from int (applies to choice etc.). */
 129     virtual void SetControlIntValue( wxPGProperty* property,
 130                                      wxWindow* ctrl, int value ) const;
 131
 132     /**
 133         Inserts item to existing control. Index -1 means end of list.
 134         Default implementation does nothing. Returns index of item added.
 135     */
 136     virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;
 137
 138     /**
 139         Deletes item from existing control.
 140         Default implementation does nothing.
 141     */
 142     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 143
 144     /**
 145         Extra processing when control gains focus.
 146         For example, wxTextCtrl based controls should select all text.
 147     */
 148     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 149
 150     /**
 151         Returns @true if control itself can contain the custom image.
 152         Default implementation returns @false.
 153     */
 154     virtual bool CanContainCustomImage() const;
 155 };
 156
 157
 158
 159 /**
 160     @class wxPGMultiButton
 161
 162     This class can be used to have multiple buttons in a property editor.
 163     You will need to create a new property editor class, override CreateControls,
 164     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 165
 166     For instance, here we add three buttons to a TextCtrl editor:
 167
 168     @code
 169     #include <wx/propgrid/editors.h>
 170
 171     class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
 172     {
 173         DECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor)
 174     public:
 175         wxSampleMultiButtonEditor() {}
 176         virtual ~wxSampleMultiButtonEditor() {}
 177
 178         virtual wxString GetName() const { return "SampleMultiButtonEditor"; }
 179
 180         virtual wxPGWindowList CreateControls( wxPropertyGrid* propGrid,
 181                                                wxPGProperty* property,
 182                                                const wxPoint& pos,
 183                                                const wxSize& sz ) const;
 184         virtual bool OnEvent( wxPropertyGrid* propGrid,
 185                               wxPGProperty* property,
 186                               wxWindow* ctrl,
 187                               wxEvent& event ) const;
 188     };
 189
 190     IMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor)
 191
 192     wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
 193                                                               wxPGProperty* property,
 194                                                               const wxPoint& pos,
 195                                                               const wxSize& sz ) const
 196     {
 197         // Create and populate buttons-subwindow
 198         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 199
 200         // Add two regular buttons
 201         buttons->Add( "..." );
 202         buttons->Add( "A" );
 203         // Add a bitmap button
 204         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 205
 206         // Create the 'primary' editor control (textctrl in this case)
 207         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
 208                                  ( propGrid, property, pos,
 209                                    buttons->GetPrimarySize() );
 210
 211         // Finally, move buttons-subwindow to correct position and make sure
 212         // returned wxPGWindowList contains our custom button list.
 213         buttons->Finalize(propGrid, pos);
 214
 215         wndList.SetSecondary( buttons );
 216         return wndList;
 217     }
 218
 219     bool wxSampleMultiButtonEditor::OnEvent( wxPropertyGrid* propGrid,
 220                                              wxPGProperty* property,
 221                                              wxWindow* ctrl,
 222                                              wxEvent& event ) const
 223     {
 224         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 225         {
 226             wxPGMultiButton* buttons = (wxPGMultiButton*) propGrid->GetEditorControlSecondary();
 227
 228             if ( event.GetId() == buttons->GetButtonId(0) )
 229             {
 230                 // Do something when first button is pressed
 231                 return true;
 232             }
 233             if ( event.GetId() == buttons->GetButtonId(1) )
 234             {
 235                 // Do something when second button is pressed
 236                 return true;
 237             }
 238             if ( event.GetId() == buttons->GetButtonId(2) )
 239             {
 240                 // Do something when third button is pressed
 241                 return true;
 242             }
 243         }
 244         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 245     }
 246     @endcode
 247
 248     Further to use this editor, code like this can be used:
 249
 250     @code
 251         // Register editor class - needs only to be called once
 252         wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
 253         wxPropertyGrid::RegisterEditorClass( multiButtonEditor );
 254
 255         // Insert the property that will have multiple buttons
 256         propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
 257
 258         // Change property to use editor created in the previous code segment
 259         propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );
 260     @endcode
 261
 262     @library{wxpropgrid}
 263     @category{propgrid}
 264 */
 265 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 266 {
 267 public:
 268     /**
 269         Constructor.
 270     */
 271     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 272
 273     /**
 274         Destructor.
 275     */
 276     virtual ~wxPGMultiButton() { }
 277
 278     /**
 279         Adds new button, with given label.
 280     */
 281     void Add( const wxString& label, int id = -2 );
 282
 283     /**
 284         Adds new bitmap button.
 285     */
 286     void Add( const wxBitmap& bitmap, int id = -2 );
 287
 288     /**
 289         Call this in CreateControls() of your custom editor class
 290         after all buttons have been added.
 291
 292         @param propGrid
 293             wxPropertyGrid given in CreateControls().
 294
 295         @param pos
 296             wxPoint given in CreateControls().
 297     */
 298     void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
 299
 300     /**
 301         Returns pointer to one of the buttons.
 302     */
 303     wxWindow* GetButton( unsigned int i );
 304
 305     /**
 306         Returns Id of one of the buttons.
 307         This is utility function to be used in event handlers.
 308     */
 309     int GetButtonId( unsigned int i ) const;
 310
 311     /**
 312         Returns number of buttons.
 313     */
 314     unsigned int GetCount();
 315
 316     /**
 317         Returns size of primary editor control, as appropriately
 318         reduced by number of buttons present.
 319     */
 320     wxSize GetPrimarySize() const;
 321 };
 322