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         - Unlike in previous version of wxPropertyGrid, it is no longer
  74           necessary to call wxEvtHandler::Connect() for interesting editor
  75           events. Instead, all events from control are now automatically
  76           forwarded to wxPGEditor::OnEvent() and wxPGProperty::OnEvent().
  77     */
  78     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid,
  79                                            wxPGProperty* property,
  80                                            const wxPoint& pos,
  81                                            const wxSize& size ) const = 0;
  82
  83     /** Loads value from property to the control. */
  84     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
  85
  86     /**
  87         Draws value for given property.
  88     */
  89     virtual void DrawValue( wxDC& dc, const wxRect& rect,
  90                             wxPGProperty* property, const wxString& text ) const;
  91
  92     /**
  93         Handles events. Returns @true if value in control was modified
  94         (see wxPGProperty::OnEvent() for more information).
  95
  96         @remarks wxPropertyGrid will automatically unfocus the editor when
  97                  wxEVT_COMMAND_TEXT_ENTER is received and when it results in
  98                  property value being modified. This happens regardless of
  99                  editor type (ie. behavior is same for any wxTextCtrl and
 100                  wxComboBox based editor).
 101     */
 102     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 103         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 104
 105     /**
 106         Returns value from control, via parameter 'variant'.
 107         Usually ends up calling property's StringToValue() or IntToValue().
 108         Returns @true if value was different.
 109     */
 110     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,
 111                                       wxWindow* ctrl ) const;
 112
 113     /** Sets value in control to unspecified. */
 114     virtual void SetValueToUnspecified( wxPGProperty* property,
 115                                         wxWindow* ctrl ) const = 0;
 116
 117     /** Sets control's value specifically from string. */
 118     virtual void SetControlStringValue( wxPGProperty* property,
 119                                         wxWindow* ctrl, const wxString& txt ) const;
 120
 121     /** Sets control's value specifically from int (applies to choice etc.). */
 122     virtual void SetControlIntValue( wxPGProperty* property,
 123                                      wxWindow* ctrl, int value ) const;
 124
 125     /**
 126         Inserts item to existing control. Index -1 means end of list.
 127         Default implementation does nothing. Returns index of item added.
 128     */
 129     virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;
 130
 131     /**
 132         Deletes item from existing control.
 133         Default implementation does nothing.
 134     */
 135     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 136
 137     /**
 138         Extra processing when control gains focus.
 139         For example, wxTextCtrl based controls should select all text.
 140     */
 141     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 142
 143     /**
 144         Returns @true if control itself can contain the custom image.
 145         Default implementation returns @false.
 146     */
 147     virtual bool CanContainCustomImage() const;
 148 };
 149
 150
 151
 152 /**
 153     @class wxPGMultiButton
 154
 155     This class can be used to have multiple buttons in a property editor.
 156     You will need to create a new property editor class, override CreateControls,
 157     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 158
 159     For instance, here we add three buttons to a TextCtrl editor:
 160
 161     @code
 162     #include <wx/propgrid/editors.h>
 163
 164     class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
 165     {
 166         DECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor)
 167     public:
 168         wxSampleMultiButtonEditor() {}
 169         virtual ~wxSampleMultiButtonEditor() {}
 170
 171         virtual wxString GetName() const { return "SampleMultiButtonEditor"; }
 172
 173         virtual wxPGWindowList CreateControls( wxPropertyGrid* propGrid,
 174                                                wxPGProperty* property,
 175                                                const wxPoint& pos,
 176                                                const wxSize& sz ) const;
 177         virtual bool OnEvent( wxPropertyGrid* propGrid,
 178                               wxPGProperty* property,
 179                               wxWindow* ctrl,
 180                               wxEvent& event ) const;
 181     };
 182
 183     IMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor)
 184
 185     wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
 186                                                               wxPGProperty* property,
 187                                                               const wxPoint& pos,
 188                                                               const wxSize& sz ) const
 189     {
 190         // Create and populate buttons-subwindow
 191         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 192
 193         // Add two regular buttons
 194         buttons->Add( "..." );
 195         buttons->Add( "A" );
 196         // Add a bitmap button
 197         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 198
 199         // Create the 'primary' editor control (textctrl in this case)
 200         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
 201                                  ( propGrid, property, pos,
 202                                    buttons->GetPrimarySize() );
 203
 204         // Finally, move buttons-subwindow to correct position and make sure
 205         // returned wxPGWindowList contains our custom button list.
 206         buttons->Finalize(propGrid, pos);
 207
 208         wndList.SetSecondary( buttons );
 209         return wndList;
 210     }
 211
 212     bool wxSampleMultiButtonEditor::OnEvent( wxPropertyGrid* propGrid,
 213                                              wxPGProperty* property,
 214                                              wxWindow* ctrl,
 215                                              wxEvent& event ) const
 216     {
 217         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 218         {
 219             wxPGMultiButton* buttons = (wxPGMultiButton*) propGrid->GetEditorControlSecondary();
 220
 221             if ( event.GetId() == buttons->GetButtonId(0) )
 222             {
 223                 // Do something when the first button is pressed
 224                 // Return true if the action modified the value in editor.
 225                 ...
 226             }
 227             if ( event.GetId() == buttons->GetButtonId(1) )
 228             {
 229                 // Do something when the second button is pressed
 230                 ...
 231             }
 232             if ( event.GetId() == buttons->GetButtonId(2) )
 233             {
 234                 // Do something when the third button is pressed
 235                 ...
 236             }
 237         }
 238         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 239     }
 240     @endcode
 241
 242     Further to use this editor, code like this can be used:
 243
 244     @code
 245         // Register editor class - needs only to be called once
 246         wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
 247         wxPropertyGrid::RegisterEditorClass( multiButtonEditor );
 248
 249         // Insert the property that will have multiple buttons
 250         propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
 251
 252         // Change property to use editor created in the previous code segment
 253         propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );
 254     @endcode
 255
 256     @library{wxpropgrid}
 257     @category{propgrid}
 258 */
 259 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 260 {
 261 public:
 262     /**
 263         Constructor.
 264     */
 265     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 266
 267     /**
 268         Destructor.
 269     */
 270     virtual ~wxPGMultiButton() { }
 271
 272     /**
 273         Adds new button, with given label.
 274     */
 275     void Add( const wxString& label, int id = -2 );
 276
 277     /**
 278         Adds new bitmap button.
 279     */
 280     void Add( const wxBitmap& bitmap, int id = -2 );
 281
 282     /**
 283         Call this in CreateControls() of your custom editor class
 284         after all buttons have been added.
 285
 286         @param propGrid
 287             wxPropertyGrid given in CreateControls().
 288
 289         @param pos
 290             wxPoint given in CreateControls().
 291     */
 292     void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
 293
 294     /**
 295         Returns pointer to one of the buttons.
 296     */
 297     wxWindow* GetButton( unsigned int i );
 298
 299     /**
 300         Returns Id of one of the buttons.
 301         This is utility function to be used in event handlers.
 302     */
 303     int GetButtonId( unsigned int i ) const;
 304
 305     /**
 306         Returns number of buttons.
 307     */
 308     unsigned int GetCount();
 309
 310     /**
 311         Returns size of primary editor control, as appropriately
 312         reduced by number of buttons present.
 313     */
 314     wxSize GetPrimarySize() const;
 315 };
 316