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 builtin property editors are: TextCtrl, Choice,
  17       ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional editors
  18       include SpinCtrl and DatePickerCtrl, but using them requires calling
  19       wxPropertyGrid::RegisterAdditionalEditors() prior use.
  20
  21     - Pointer to builtin editor is available as wxPGEditor_EditorName
  22       (eg. wxPGEditor_TextCtrl).
  23
  24     - To add new editor you need to register it first using static function
  25       wxPropertyGrid::RegisterEditorClass(), with code like this:
  26         @code
  27             wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");
  28         @endcode
  29       After that, wxPropertyGrid will take ownership of the given object, but
  30       you should still store editorPointer somewhere, so you can pass it to
  31       wxPGProperty::SetEditor(), or return it from wxPGEditor::DoGetEditorClass().
  32
  33     @library{wxpropgrid}
  34     @category{propgrid}
  35 */
  36 class wxPGEditor : public wxObject
  37 {
  38 public:
  39
  40     /** Constructor. */
  41     wxPGEditor()
  42         : wxObject()
  43     {
  44         m_clientData = NULL;
  45     }
  46
  47     /** Destructor. */
  48     virtual ~wxPGEditor();
  49
  50     /** Returns pointer to the name of the editor. For example, wxPG_EDITOR(TextCtrl)
  51         has name "TextCtrl". This method is autogenerated for custom editors.
  52     */
  53     virtual wxString GetName() const = 0;
  54
  55     /** Instantiates editor controls.
  56         @param propgrid
  57         wxPropertyGrid to which the property belongs (use as parent for control).
  58         @param property
  59         Property for which this method is called.
  60         @param pos
  61         Position, inside wxPropertyGrid, to create control(s) to.
  62         @param size
  63         Initial size for control(s).
  64
  65         @remarks
  66         - Primary control shall use id wxPG_SUBID1, and secondary (button) control
  67           shall use wxPG_SUBID2.
  68         - Implementation shoud use connect all necessary events to the
  69           wxPropertyGrid::OnCustomEditorEvent. For Example:
  70             @code
  71                 // Relays wxEVT_COMMAND_TEXT_UPDATED events of primary editor
  72                 // control to the OnEvent.
  73                 // NOTE: This event in particular is actually automatically conveyed, but
  74                 //   it is just used as an example.
  75                 propgrid->Connect( wxPG_SUBID1, wxEVT_COMMAND_TEXT_UPDATED,
  76                                   wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent) );
  77             @endcode
  78             OnCustomEditorEvent will then forward events, first to wxPGEditor::OnEvent and then to wxPGProperty::OnEvent.
  79
  80     */
  81     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid, wxPGProperty* property,
  82         const wxPoint& pos, const wxSize& size ) const = 0;
  83
  84     /** Loads value from property to the control. */
  85     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
  86
  87     /** Draws value for given property.
  88     */
  89     virtual void DrawValue( wxDC& dc, const wxRect& rect, wxPGProperty* property, const wxString& text ) const;
  90
  91     /** Handles events. Returns true if value in control was modified
  92         (see wxPGProperty::OnEvent for more information).
  93     */
  94     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
  95         wxWindow* wnd_primary, wxEvent& event ) const = 0;
  96
  97     /** Returns value from control, via parameter 'variant'.
  98         Usually ends up calling property's StringToValue or IntToValue.
  99         Returns true if value was different.
 100     */
 101     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property, wxWindow* ctrl ) const;
 102
 103     /** Sets value in control to unspecified. */
 104     virtual void SetValueToUnspecified( wxPGProperty* property, wxWindow* ctrl ) const = 0;
 105
 106     /** Sets control's value specifically from string. */
 107     virtual void SetControlStringValue( wxPGProperty* property, wxWindow* ctrl, const wxString& txt ) const;
 108
 109     /** Sets control's value specifically from int (applies to choice etc.). */
 110     virtual void SetControlIntValue( wxPGProperty* property, wxWindow* ctrl, int value ) const;
 111
 112     /** Inserts item to existing control. Index -1 means appending.
 113         Default implementation does nothing. Returns index of item added.
 114     */
 115     virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;
 116
 117     /** Deletes item from existing control.
 118         Default implementation does nothing.
 119     */
 120     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 121
 122     /** Extra processing when control gains focus. For example, wxTextCtrl
 123         based controls should select all text.
 124     */
 125     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 126
 127     /** Returns true if control itself can contain the custom image. Default is
 128         to return false.
 129     */
 130     virtual bool CanContainCustomImage() const;
 131
 132     //
 133     // This member is public so scripting language bindings
 134     // wrapper code can access it freely.
 135     void*       m_clientData;
 136 };
 137
 138 // -----------------------------------------------------------------------
 139
 140 /** @class wxPGMultiButton
 141
 142     This class can be used to have multiple buttons in a property editor.
 143     You will need to create a new property editor class, override CreateControls,
 144     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 145     For instance, here we add three buttons to a textctrl editor:
 146
 147     @code
 148
 149     #include <wx/propgrid/editors.h>
 150
 151     class wxMultiButtonTextCtrlEditor : public wxPGTextCtrlEditor
 152     {
 153         WX_PG_DECLARE_EDITOR_CLASS(wxMultiButtonTextCtrlEditor)
 154     public:
 155         wxMultiButtonTextCtrlEditor() {}
 156         virtual ~wxMultiButtonTextCtrlEditor() {}
 157
 158         wxPG_DECLARE_CREATECONTROLS
 159         virtual bool OnEvent( wxPropertyGrid* propGrid,
 160                               wxPGProperty* property,
 161                               wxWindow* ctrl,
 162                               wxEvent& event ) const;
 163
 164     };
 165
 166     WX_PG_IMPLEMENT_EDITOR_CLASS(MultiButtonTextCtrlEditor, wxMultiButtonTextCtrlEditor,
 167                                  wxPGTextCtrlEditor)
 168
 169     wxPGWindowList wxMultiButtonTextCtrlEditor::CreateControls( wxPropertyGrid* propGrid,
 170                                                                 wxPGProperty* property,
 171                                                                 const wxPoint& pos,
 172                                                                 const wxSize& sz ) const
 173     {
 174         // Create and populate buttons-subwindow
 175         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 176
 177         // Add two regular buttons
 178         buttons->Add( "..." );
 179         buttons->Add( "A" );
 180         // Add a bitmap button
 181         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 182
 183         // Create the 'primary' editor control (textctrl in this case)
 184         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
 185                                  ( propGrid, property, pos, buttons->GetPrimarySize() );
 186
 187         // Finally, move buttons-subwindow to correct position and make sure
 188         // returned wxPGWindowList contains our custom button list.
 189         buttons->FinalizePosition(pos);
 190
 191         wndList.SetSecondary( buttons );
 192         return wndList;
 193     }
 194
 195     bool wxMultiButtonTextCtrlEditor::OnEvent( wxPropertyGrid* propGrid,
 196                                                wxPGProperty* property,
 197                                                wxWindow* ctrl,
 198                                                wxEvent& event ) const
 199     {
 200         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 201         {
 202             wxPGMultiButton* buttons = (wxPGMultiButton*) propGrid->GetEditorControlSecondary();
 203
 204             if ( event.GetId() == buttons->GetButtonId(0) )
 205             {
 206                 // Do something when first button is pressed
 207                 return true;
 208             }
 209             if ( event.GetId() == buttons->GetButtonId(1) )
 210             {
 211                 // Do something when first button is pressed
 212                 return true;
 213             }
 214             if ( event.GetId() == buttons->GetButtonId(2) )
 215             {
 216                 // Do something when second button is pressed
 217                 return true;
 218             }
 219         }
 220         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 221     }
 222
 223     @endcode
 224
 225     Further to use this editor, code like this can be used:
 226
 227     @code
 228
 229         // Register editor class - needs only to be called once
 230         wxPGRegisterEditorClass( MultiButtonTextCtrlEditor );
 231
 232         // Insert the property that will have multiple buttons
 233         propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
 234
 235         // Change property to use editor created in the previous code segment
 236         propGrid->SetPropertyEditor( "MultipleButtons", wxPG_EDITOR(MultiButtonTextCtrlEditor) );
 237
 238     @endcode
 239
 240     @library{wxpropgrid}
 241     @category{propgrid}
 242 */
 243 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 244 {
 245 public:
 246
 247     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 248
 249     virtual ~wxPGMultiButton() { }
 250
 251     wxWindow* GetButton( unsigned int i ) { return (wxWindow*) m_buttons[i]; }
 252     const wxWindow* GetButton( unsigned int i ) const { return (const wxWindow*) m_buttons[i]; }
 253
 254     /** Utility function to be used in event handlers.
 255     */
 256     int GetButtonId( unsigned int i ) const { return GetButton(i)->GetId(); }
 257
 258     /** Returns number of buttons.
 259     */
 260     int GetCount() const { return m_buttons.Count(); }
 261
 262     void Add( const wxString& label, int id = -2 );
 263     void Add( const wxBitmap& bitmap, int id = -2 );
 264
 265     wxSize GetPrimarySize() const
 266     {
 267         return wxSize(m_fullEditorSize.x - m_buttonsWidth, m_fullEditorSize.y);
 268     }
 269
 270     void FinalizePosition( const wxPoint& pos )
 271     {
 272         Move( pos.x + m_fullEditorSize.x - m_buttonsWidth, pos.y );
 273     }
 274 };
 275
 276 // -----------------------------------------------------------------------
 277
 278 #endif // _WX_PROPGRID_EDITORS_H_