From 0dfff6740755754c36e47e5961e9e5fbd1cd4d4e Mon Sep 17 00:00:00 2001 From: =?utf8?q?W=C5=82odzimierz=20Skiba?= Date: Wed, 14 Jun 2006 19:15:29 +0000 Subject: [PATCH] [ 1495657 ] Documentation for wxComboCtrl and wxOwnerDrawnComboBox. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@39731 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/category.tex | 2 + docs/latex/wx/classes.tex | 3 + docs/latex/wx/comboctrl.tex | 628 +++++++++++++++++++++++++++++++++++ docs/latex/wx/combopopup.tex | 183 ++++++++++ docs/latex/wx/odcbox.tex | 204 ++++++++++++ 5 files changed, 1020 insertions(+) create mode 100644 docs/latex/wx/comboctrl.tex create mode 100644 docs/latex/wx/combopopup.tex create mode 100644 docs/latex/wx/odcbox.tex diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex index aaaa0be5d1..f7a2271ebb 100644 --- a/docs/latex/wx/category.tex +++ b/docs/latex/wx/category.tex @@ -94,6 +94,7 @@ that are not static can have \helpref{validators}{wxvalidator} associated with t \twocolitem{\helpref{wxCheckListBox}{wxchecklistbox}}{A listbox with a checkbox to the left of each item} \twocolitem{\helpref{wxChoice}{wxchoice}}{Choice control (a combobox without the editable area)} \twocolitem{\helpref{wxComboBox}{wxcombobox}}{A choice with an editable area} +\twocolitem{\helpref{wxComboCtrl}{wxcomboctrl}}{A combobox with application defined popup} \twocolitem{\helpref{wxGauge}{wxgauge}}{A control to represent a varying quantity, such as time remaining} \twocolitem{\helpref{wxGenericDirCtrl}{wxgenericdirctrl}}{A control for displaying a directory tree} \twocolitem{\helpref{wxHtmlListBox}{wxhtmllistbox}}{A listbox showing HTML content} @@ -101,6 +102,7 @@ that are not static can have \helpref{validators}{wxvalidator} associated with t \twocolitem{\helpref{wxListBox}{wxlistbox}}{A list of strings for single or multiple selection} \twocolitem{\helpref{wxListCtrl}{wxlistctrl}}{A control for displaying lists of strings and/or icons, plus a multicolumn report view} \twocolitem{\helpref{wxListView}{wxlistview}}{A simpler interface ({\it fa\c{c}ade} for wxListCtrl in report mode} +\twocolitem{\helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}}{A combobox with owner-drawn list items} \twocolitem{\helpref{wxTextCtrl}{wxtextctrl}}{Single or multiline text editing control} \twocolitem{\helpref{wxTreeCtrl}{wxtreectrl}}{Tree (hierarchy) control} \twocolitem{\helpref{wxScrollBar}{wxscrollbar}}{Scrollbar control} diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex index fc455991b4..7424b4ac3b 100644 --- a/docs/latex/wx/classes.tex +++ b/docs/latex/wx/classes.tex @@ -46,6 +46,8 @@ \input colour.tex \input colordlg.tex \input combobox.tex +\input comboctrl.tex +\input combopopup.tex \input command.tex \input cmdevent.tex \input cmdproc.tex @@ -249,6 +251,7 @@ \input nbsizer.tex \input notifevt.tex \input object.tex +\input odcbox.tex \input outptstr.tex \input pagedlg.tex \input paintdc.tex diff --git a/docs/latex/wx/comboctrl.tex b/docs/latex/wx/comboctrl.tex new file mode 100644 index 0000000000..f7b7921cfb --- /dev/null +++ b/docs/latex/wx/comboctrl.tex @@ -0,0 +1,628 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: comboctrl.tex +%% Purpose: wxComboCtrl docs +%% Author: Jaakko Salli +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) Jaakko Salli +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxComboCtrl}}\label{wxcomboctrl} + +A combo control is a generic combobox that allows totally +custom popup. In addition it has other customization features. +For instance, position and size of the dropdown button +can be changed. + +\wxheading{Setting Custom Popup for wxComboCtrl} + +wxComboCtrl needs to be told somehow which control to use +and this is done by SetPopupControl(). However, we need +something more than just a wxControl in this method as, +for example, we need to call SetStringValue("initial text value") +and wxControl doesn't have such method. So we also need a +\helpref{wxComboPopup}{wxcombopopup} which is an interface which +must be implemented by a control to be usable as a popup. + +We couldn't derive wxComboPopup from wxControl as this would make it +impossible to have a class deriving from a wxWidgets control and from +it, so instead it is just a mix-in. + +Here's a minimal sample of \helpref{wxListView}{wxlistview} popup: + +\begin{verbatim} + +#include +#include + +class wxListViewComboPopup : public wxListView, + public wxComboPopup +{ +public: + + // Initialize member variables + virtual void Init() + { + m_value = -1; + } + + // Create popup control + virtual bool Create(wxWindow* parent) + { + return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize); + } + + // Return pointer to the created control + virtual wxWindow *GetControl() { return this; } + + // Translate string into a list selection + virtual void SetStringValue(const wxString& s) + { + int n = wxListView::FindItem(-1,s); + if ( n >= 0 && n < wxListView::GetItemCount() ) + wxListView::Select(n); + } + + // Get list selection as a string + virtual wxString GetStringValue() const + { + if ( m_value >= 0 ) + return wxListView::GetItemText(m_value); + return wxEmptyString; + } + + // Do mouse hot-tracking (which is typical in list popups) + void OnMouseMove(wxMouseEvent& event) + { + // TODO: Move selection to cursor + } + + // On mouse left up, set the value and close the popup + void OnMouseClick(wxMouseEvent& WXUNUSED(event)) + { + m_value = wxListView::GetFirstSelected(); + + // TODO: Send event as well + + Dismiss(); + } + +protected: + + int m_value; // current item index + +private: + DECLARE_EVENT_TABLE() +}; + +BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView) + EVT_MOTION(wxListViewComboPopup::OnMouseMove) + EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick) +END_EVENT_TABLE() + +\end{verbatim} + +Here's how you would create and populate it in a dialog constructor: + +\begin{verbatim} + + wxComboCtrl* comboCtrl = new wxComboCtrl(this,wxID_ANY,wxEmptyString); + + wxListViewComboPopup* popupCtrl = new wxListViewComboPopup(); + + comboCtrl->SetPopupControl(popupCtrl); + + // Populate using wxListView methods + popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("First Item")); + popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Second Item")); + popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Third Item")); + +\end{verbatim} + +\wxheading{Derived from} + +\helpref{wxControl}{wxcontrol}\\ +\helpref{wxWindow}{wxwindow}\\ +\helpref{wxEvtHandler}{wxevthandler}\\ +\helpref{wxObject}{wxobject} + +\wxheading{Include files} + + + +\wxheading{Window styles} + +\begin{twocollist}\itemsep=0pt +\twocolitem{\windowstyle{wxCB\_READONLY}}{Text will not be editable.} +\twocolitem{\windowstyle{wxCB\_SORT}}{Sorts the entries in the list alphabetically.} +\twocolitem{\windowstyle{wxPROCESS\_ENTER}}{The control will generate +the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key +is either processed internally by the control or used for navigation between +dialog controls). Windows only.} +\twocolitem{\windowstyle{wxCC\_SPECIAL\_DCLICK}}{Double-clicking triggers a call +to popup's OnComboDoubleClick. Actual behaviour is defined by a derived +class. For instance, wxOwnerDrawnComboBox will cycle an item. This style only +applies if wxCB\_READONLY is used as well.} +\twocolitem{\windowstyle{wxCC\_ALT\_KEYS}}{Use keyboard behaviour alternate +to platform default: up and down keys will show popup (instead of cycling value, +for instance, on wxMSW).} +\twocolitem{\windowstyle{wxCC\_STD\_BUTTON}}{Drop button will behave +more like a standard push button.} +\end{twocollist} + +See also \helpref{window styles overview}{windowstyles}. + +\wxheading{Event handling} + +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED event, +when the text changes.} +\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_ENTER event, +when is pressed in the combo control.} +\end{twocollist} + +\wxheading{See also} + +\helpref{wxComboBox}{wxcombobox}, \helpref{wxChoice}{wxchoice}, +\helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}, +\rtfsp\helpref{wxComboPopup}{wxcombopopup}, \helpref{wxCommandEvent}{wxcommandevent} + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxComboCtrl::wxComboCtrl}\label{wxcomboctrlctor} + +\func{}{wxComboCtrl}{\void} + +Default constructor. + +\func{}{wxComboCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp +\param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp +\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboCtrl"}} + +Constructor, creating and showing a combo control. + +\wxheading{Parameters} + +\docparam{parent}{Parent window. Must not be NULL.} + +\docparam{id}{Window identifier. A value of -1 indicates a default value.} + +\docparam{value}{Initial selection string. An empty string indicates no selection.} + +\docparam{pos}{Window position.} + +\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized +appropriately.} + +\docparam{style}{Window style. See \helpref{wxComboCtrl}{wxcomboctrl}.} + +\docparam{validator}{Window validator.} + +\docparam{name}{Window name.} + +\wxheading{See also} + +\helpref{wxComboCtrl::Create}{wxcomboctrlcreate}, \helpref{wxValidator}{wxvalidator} + + +\membersection{wxComboCtrl::\destruct{wxComboCtrl}}\label{wxcomboctrldtor} + +\func{}{\destruct{wxComboCtrl}}{\void} + +Destructor, destroying the combo control. + + +\membersection{wxComboCtrl::Create}\label{wxcomboctrlcreate} + +\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp +\param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp +\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboCtrl"}} + +Creates the combo control for two-step construction. Derived classes +should call or replace this function. See \helpref{wxComboCtrl::wxComboCtrl}{wxcomboctrlctor}\rtfsp +for further details. + + +\membersection{wxComboCtrl::Copy}\label{wxcomboctrlcopy} + +\func{void}{Copy}{\void} + +Copies the selected text to the clipboard. + + +\membersection{wxComboCtrl::Cut}\label{wxcomboctrlcut} + +\func{void}{Cut}{\void} + +Copies the selected text to the clipboard and removes the selection. + + +\membersection{wxComboCtrl::GetBitmapDisabled}\label{wxcomboctrlgetbitmapdisabled} + +\constfunc{const wxBitmap\&}{GetBitmapDisabled}{\void} + +Returns disabled button bitmap that has been set with +\helpref{SetButtonBitmaps}{wxcomboctrlsetbuttonbitmaps}. + +\wxheading{Return value} + +A reference to the disabled state bitmap. + + +\membersection{wxComboCtrl::GetBitmapHover}\label{wxcomboctrlgetbitmaphover} + +\constfunc{const wxBitmap\&}{GetBitmapHover}{\void} + +Returns button mouse hover bitmap that has been set with +\helpref{SetButtonBitmaps}{wxcomboctrlsetbuttonbitmaps}. + +\wxheading{Return value} + +A reference to the mouse hover state bitmap. + + +\membersection{wxComboCtrl::GetBitmapNormal}\label{wxcomboctrlgetbitmapnormal} + +\constfunc{const wxBitmap\&}{GetBitmapNormal}{\void} + +Returns default button bitmap that has been set with +\helpref{SetButtonBitmaps}{wxcomboctrlsetbuttonbitmaps}. + +\wxheading{Return value} + +A reference to the normal state bitmap. + + +\membersection{wxComboCtrl::GetBitmapPressed}\label{wxcomboctrlgetbitmappressed} + +\constfunc{const wxBitmap\&}{GetBitmapPressed}{\void} + +Returns depressed button bitmap that has been set with +\helpref{SetButtonBitmaps}{wxcomboctrlsetbuttonbitmaps}. + +\wxheading{Return value} + +A reference to the depressed state bitmap. + + +\membersection{wxComboCtrl::GetCustomPaintWidth}\label{wxcomboctrlgetcustompaintwidth} + +\constfunc{int}{GetCustomPaintWidth}{\void} + +Returns custom painted area in control. + +\wxheading{See also} + +\helpref{wxComboCtrl::SetCustomPaintWidth}{wxcomboctrlsetcustompaintwidth}. + + +\membersection{wxComboCtrl::GetFeatures}\label{wxcomboctrlgetfeatures} + +\func{static int}{GetFeatures}{\void} + +Returns features supported by wxComboCtrl. If needed feature is missing, +you need to instead use wxGenericComboCtrl, which however may lack +native look and feel (but otherwise sports identical API). + +\wxheading{Return value} + +Value returned is a combination of following flags: + +\twocolwidtha{8cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{{\tt wxComboCtrlFeatures::MovableButton}}{Button can +be on either side of the control.} +\twocolitem{{\tt wxComboCtrlFeatures::BitmapButton}}{Button may +be replaced with bitmap.} +\twocolitem{{\tt wxComboCtrlFeatures::ButtonSpacing}}{Button can +have spacing.} +\twocolitem{{\tt wxComboCtrlFeatures::TextIndent}}{SetTextIndent +works.} +\twocolitem{{\tt wxComboCtrlFeatures::PaintControl}}{Combo control +itself can be custom painted.} +\twocolitem{{\tt wxComboCtrlFeatures::PaintWritable}}{A variable- +width area in front of writable combo control's textctrl can +be custom painted.} +\twocolitem{{\tt wxComboCtrlFeatures::Borderless}}{wxNO\_BORDER +window style works.} +\twocolitem{{\tt wxComboCtrlFeatures::All}}{All of the +above.} +\end{twocollist} + + +\membersection{wxComboCtrl::GetInsertionPoint}\label{wxcomboctrlgetinsertionpoint} + +\constfunc{long}{GetInsertionPoint}{\void} + +Returns the insertion point for the combo control's text field. + +\textbf{Note:} Under wxMSW, this function always returns $0$ if the combo control +doesn't have the focus. + + +\membersection{wxComboCtrl::GetLastPosition}\label{wxcomboctrlgetlastposition} + +\constfunc{long}{GetLastPosition}{\void} + +Returns the last position in the combo control text field. + + +\membersection{wxComboCtrl::GetPopupControl}\label{wxcomboctrlgetpopupcontrol} + +\func{wxComboPopup*}{GetPopupControl}{\void} + +Returns current popup interface that has been set with SetPopupControl. + + +\membersection{wxComboCtrl::GetPopupWindow}\label{wxcomboctrlgetpopupwindow} + +\constfunc{wxWindow*}{GetPopupWindow}{\void} + +Returns popup window containing the popup control. + + +\membersection{wxComboCtrl::GetTextCtrl}\label{wxcomboctrlgettextctrl} + +\constfunc{wxTextCtrl*}{GetTextCtrl}{\void} + +Get the text control which is part of the combo control. + + +\membersection{wxComboCtrl::GetTextIndent}\label{wxcomboctrlgettextindent} + +\constfunc{wxCoord}{GetTextIndent}{\void} + +Returns actual indentation in pixels. + + +\membersection{wxComboCtrl::GetValue}\label{wxcomboctrlgetvalue} + +\constfunc{wxString}{GetValue}{\void} + +Returns text representation of the current value. For writable +combo control it always returns the value in the text field. + + +\membersection{wxComboCtrl::HidePopup}\label{wxcomboctrlhidepopup} + +\func{void}{HidePopup}{\void} + +Dismisses the popup window. + + +\membersection{wxComboCtrl::IsPopupShown}\label{wxcomboctrlispopupshown} + +\constfunc{bool}{IsPopupShown}{\void} + +Returns \true if the popup is currently shown + + +\membersection{wxComboCtrl::OnButtonClick}\label{wxcomboctrlonbuttonclick} + +\func{void}{OnButtonClick}{\void} + +Implement in a derived class to define what happens on +dropdown button click. + +Default action is to show the popup. + + +\membersection{wxComboCtrl::Paste}\label{wxcomboctrlpaste} + +\func{void}{Paste}{\void} + +Pastes text from the clipboard to the text field. + + +\membersection{wxComboCtrl::Remove}\label{wxcomboctrlremove} + +\func{void}{Remove}{\param{long }{from}, \param{long }{to}} + +Removes the text between the two positions in the combo control text field. + +\wxheading{Parameters} + +\docparam{from}{The first position.} + +\docparam{to}{The last position.} + + +\membersection{wxComboCtrl::Replace}\label{wxcomboctrlreplace} + +\func{void}{Replace}{\param{long }{from}, \param{long }{to}, \param{const wxString\& }{value}} + +Replaces the text between two positions with the given text, in the combo control text field. + +\wxheading{Parameters} + +\docparam{from}{The first position.} + +\docparam{to}{The second position.} + +\docparam{text}{The text to insert.} + + +\membersection{wxComboCtrl::SetButtonBitmaps}\label{wxcomboctrlsetbuttonbitmaps} + +\func{void}{SetButtonBitmaps}{\param{const wxBitmap\& }{bmpNormal}, \param{bool }{pushButtonBg = false}, \param{const wxBitmap\& }{bmpPressed = wxNullBitmap}, \param{const wxBitmap\& }{bmpHover = wxNullBitmap}, \param{const wxBitmap\& }{bmpDisabled = wxNullBitmap}} + +Sets custom dropdown button graphics. + +\wxheading{Parameters} + +\docparam{bmpNormal}{Default button image.} +\docparam{pushButtonBg}{If \true, blank push button background is painted +below the image.} +\docparam{bmpPressed}{Depressed button image.} +\docparam{bmpHover}{Button image when mouse hovers above it. This +should be ignored on platforms and themes that do not generally draw +different kind of button on mouse hover.} +\docparam{bmpDisabled}{Disabled button image.} + + +\membersection{wxComboCtrl::SetButtonPosition}\label{wxcomboctrlsetbuttonposition} + +\func{void}{SetButtonPosition}{\param{int }{width = 0}, \param{int }{height = 0}, \param{int }{side = wxRIGHT}, \param{int }{spacingX = 0}} + +Sets size and position of dropdown button. + +\wxheading{Parameters} + +\docparam{width}{If > $0$, defines specific button width. $0$ means platform default, +while negative numbers allow adjusting smaller than default.} +\docparam{height}{Same as width.} +\docparam{side}{Indicates which side the button will be placed. +Value can be {\tt wxLEFT} or {\tt wxRIGHT}.} +\docparam{spacingX}{Horizontal spacing around the button. Default is $0$.} + + +\membersection{wxComboCtrl::SetCustomPaintWidth}\label{wxcomboctrlsetcustompaintwidth} + +\func{void}{SetCustomPaintWidth}{\param{int }{width}} + +Set width, in pixels, of custom painted area in control without {\tt wxCB\_READONLY} +style. In read-only \helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}, this is used +to indicate area that is not covered by the focus rectangle. + + +\membersection{wxComboCtrl::SetInsertionPoint}\label{wxcomboctrlsetinsertionpoint} + +\func{void}{SetInsertionPoint}{\param{long }{pos}} + +Sets the insertion point in the text field. + +\wxheading{Parameters} + +\docparam{pos}{The new insertion point.} + + +\membersection{wxComboCtrl::SetInsertionPointEnd}\label{wxcomboctrlsetinsertionpointend} + +\func{void}{SetInsertionPointEnd}{\void} + +Sets the insertion point at the end of the combo control text field. + + +\membersection{wxComboCtrl::SetPopupAnchor}\label{wxcomboctrlsetpopupanchor} + +\func{void}{SetPopupAnchor}{\param{int }{anchorSide}} + +Set side of the control to which the popup will align itself. Valid values are +{\tt wxLEFT}, {\tt wxRIGHT} and $0$. The default value $0$ means that the most appropriate +side is used (which, currently, is always {\tt wxLEFT}). + + +\membersection{wxComboCtrl::SetPopupControl}\label{wxcomboctrlsetpopupcontrol} + +\func{void}{SetPopupControl}{\param{wxComboPopup* }{popup}} + +Set popup interface class derived from wxComboPopup. +This method should be called as soon as possible after the control +has been created, unless \helpref{OnButtonClick}{wxcomboctrlonbuttonclick} +has been overridden. + + +\membersection{wxComboCtrl::SetPopupExtents}\label{wxcomboctrlsetpopupextents} + +\func{void}{SetPopupExtents}{\param{int }{extLeft}, \param{int }{extRight}} + +Extends popup size horizontally, relative to the edges of the combo control. + +\wxheading{Parameters} + +\docparam{extLeft}{How many pixel to extend beyond the left edge of the +control. Default is $0$.} +\docparam{extRight}{How many pixel to extend beyond the right edge of the +control. Default is $0$.} + +\wxheading{Remarks} + +Popup minimum width may override arguments. + +It is up to the popup to fully take this into account. + + +\membersection{wxComboCtrl::SetPopupMaxHeight}\label{wxcomboctrlsetpopupmaxheight} + +\func{void}{SetPopupMaxHeight}{\param{int }{height}} + +Sets preferred maximum height of the popup. + +\wxheading{Remarks} + +Value -1 indicates the default. + +Also, popup implementation may choose to ignore this. + + +\membersection{wxComboCtrl::SetPopupMinWidth}\label{wxcomboctrlsetpopupminwidth} + +\func{void}{SetPopupMinWidth}{\param{int }{width}} + +Sets minimum width of the popup. If wider than combo control, it will extend to the left. + +\wxheading{Remarks} + +Value -1 indicates the default. + +Also, popup implementation may choose to ignore this. + + +\membersection{wxComboCtrl::SetSelection}\label{wxcomboctrlsetselection} + +\func{void}{SetSelection}{\param{long }{from}, \param{long }{to}} + +Selects the text between the two positions, in the combo control text field. + +\wxheading{Parameters} + +\docparam{from}{The first position.} + +\docparam{to}{The second position.} + + +\membersection{wxComboCtrl::SetText}\label{wxcomboctrlsettext} + +\func{void}{SetText}{\param{const wxString\& }{value}} + +Sets the text for the text field without affecting the +popup. Thus, unlike \helpref{SetValue}{wxcomboctrlsetvalue}, it works +equally well with combo control using {\tt wxCB\_READONLY} style. + + +\membersection{wxComboCtrl::SetTextIndent}\label{wxcomboctrlsettextindent} + +\func{void}{SetTextIndent}{\param{int }{indent}} + +This will set the space in pixels between left edge of the control and the +text, regardless whether control is read-only or not. Value -1 can be +given to indicate platform default. + + +\membersection{wxComboCtrl::SetValue}\label{wxcomboctrlsetvalue} + +\func{void}{SetValue}{\param{const wxString\& }{value}} + +Sets the text for the combo control text field. + +{\bf NB:} For a combo control with {\tt wxCB\_READONLY} style the +string must be accepted by the popup (for instance, exist in the dropdown +list), otherwise the call to SetValue() is ignored + + +\membersection{wxComboCtrl::ShowPopup}\label{wxcomboctrlshowpopup} + +\func{void}{ShowPopup}{\void} + +Show the popup. + + +\membersection{wxComboCtrl::Undo}\label{wxcomboctrlundo} + +\func{void}{Undo}{\void} + +Undoes the last edit in the text field. Windows only. diff --git a/docs/latex/wx/combopopup.tex b/docs/latex/wx/combopopup.tex new file mode 100644 index 0000000000..58af6a80fd --- /dev/null +++ b/docs/latex/wx/combopopup.tex @@ -0,0 +1,183 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: combopopup.tex +%% Purpose: wxComboPopup docs +%% Author: Jaakko Salli +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) Jaakko Salli +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxComboPopup}}\label{wxcombopopup} + +In order to use a custom popup with \helpref{wxComboCtrl}{wxcomboctrl}, +an interface class must be derived from wxComboPopup. For more information +how to use it, see \helpref{Setting Custom Popup for wxComboCtrl}{wxcomboctrl}. + +\wxheading{Include files} + + + +\wxheading{See also} + +\helpref{wxComboCtrl}{wxcomboctrl} + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxComboPopup::wxComboPopup}\label{wxcombopopupwxcombopopup} + +\func{}{wxComboPopup}{\void} + +Default constructor. It is recommended that internal variables +are prepared in \helpref{Init}{wxcombopopupinit} instead +(because \helpref{m\_combo}{wxcombopopupmcombo} is not valid in constructor). + + +\membersection{wxComboPopup::m\_combo}\label{wxcombopopupmcombo} + +\member{wxComboCtrl}{m\_combo} + +Parent \helpref{wxComboCtrl}{wxcomboctrl}. This is parameter has +been prepared before \helpref{Init}{wxcombopopupinit} is called. + + +\membersection{wxComboPopup::Create}\label{wxcombopopupcreate} + +\func{bool}{Create}{\param{wxWindow* }{parent}} + +The derived class must implement this to create the popup control. + +\wxheading{Return value} + +\true if the call succeeded, \false otherwise. + + +\membersection{wxComboPopup::Dismiss}\label{wxcombopopupdismiss} + +\func{void}{Dismiss}{\void} + +Utility function that hides the popup. + + +\membersection{wxComboPopup::GetAdjustedSize}\label{wxcombopopupgetadjustedsize} + +\func{wxSize}{GetAdjustedSize}{\param{int }{minWidth}, \param{int }{prefHeight}, \param{int }{maxHeight}} + +The derived class may implement this to return adjusted size +for the popup control, according to the variables given. + +\wxheading{Parameters} + +\docparam{minWidth}{Preferred minimum width.} +\docparam{prefHeight}{Preferred height. May be -1 to indicate +no preference.} +\docparam{maxWidth}{Max height for window, as limited by +screen size.} + +\wxheading{Remarks} + +Called each time popup is about to be shown. + + +\membersection{wxComboPopup::GetControl}\label{wxcombopopupgetcontrol} + +\func{wxWindow*}{GetControl}{\void} + +The derived class must implement this to return pointer +to the associated control created in \helpref{Create}{wxcombopopupcreate}. + + +\membersection{wxComboPopup::GetStringValue}\label{wxcombopopupgetstringvalue} + +\constfunc{wxString}{GetStringValue}{\void} + +The derived class must implement this to return +string representation of the value. + + +\membersection{wxComboPopup::Init}\label{wxcombopopupinit} + +\func{void}{Init}{\void} + +The derived class must implement this to initialize +its internal variables. This method is called immediately +after construction finishes. \helpref{m\_combo}{wxcombopopupmcombo} +member variable has been initialized before the call. + + +\membersection{wxComboPopup::IsCreated}\label{wxcombopopupiscreated} + +\constfunc{bool}{IsCreated}{\void} + +Utility method that returns \true if Create has been called. + +Useful in conjunction with \helpref{LazyCreate}{wxcombopopuplazycreate}. + + +\membersection{wxComboPopup::LazyCreate}\label{wxcombopopuplazycreate} + +\func{bool}{LazyCreate}{\void} + +The derived class may implement this to return +\true if it wants to delay call to \helpref{Create}{wxcombopopupcreate} +until the popup is shown for the first time. It is more +efficient, but on the other hand it is often more convenient +to have the control created immediately. + +\wxheading{Remarks} + +Base implementation returns \false. + + +\membersection{wxComboPopup::OnComboDoubleClick}\label{wxcombopopuponcombodoubleclick} + +\func{void}{OnComboDoubleClick}{\void} + +The derived class may implement this to do something +when the parent \helpref{wxComboCtrl}{wxcomboctrl} gets double-clicked. + + +\membersection{wxComboPopup::OnComboKeyEvent}\label{wxcombopopuponcombokeyevent} + +\func{void}{OnComboKeyEvent}{\param{wxKeyEvent\& }{event}} + +The derived class may implement this to receive +key events from the parent \helpref{wxComboCtrl}{wxcomboctrl}. + +Events not handled should be skipped, as usual. + + +\membersection{wxComboPopup::OnDismiss}\label{wxcombopopupondismiss} + +\func{void}{OnDismiss}{\void} + +The derived class may implement this to do +special processing when popup is hidden. + + +\membersection{wxComboPopup::OnPopup}\label{wxcombopopuponpopup} + +\func{void}{OnPopup}{\void} + +The derived class may implement this to do +special processing when popup is shown. + + +\membersection{wxComboPopup::PaintComboControl}\label{wxcombopopuppaintcombocontrol} + +\func{void}{PaintComboControl}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}} + +The derived class may implement this to paint +the parent \helpref{wxComboCtrl}{wxcomboctrl}. + +Default implementation draws value as string. + + +\membersection{wxComboPopup::SetStringValue}\label{wxcombopopupsetstringvalue} + +\func{void}{SetStringValue}{\param{const wxString\& }{value}} + +The derived class must implement this to receive +string value changes from \helpref{wxComboCtrl}{wxcomboctrl}. diff --git a/docs/latex/wx/odcbox.tex b/docs/latex/wx/odcbox.tex new file mode 100644 index 0000000000..460966abc6 --- /dev/null +++ b/docs/latex/wx/odcbox.tex @@ -0,0 +1,204 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: odcbox.tex +%% Purpose: wxOwnerDrawnComboBox docs +%% Author: Jaakko Salli +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) Jaakko Salli +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxOwnerDrawnComboBox}}\label{wxownerdrawncombobox} + +wxOwnerDrawnComboBox is a combobox with owner-drawn list items. +In essence, it is a \helpref{wxComboCtrl}{wxcomboctrl} with +\helpref{wxVListBox}{wxvlistbox} popup and \helpref{wxControlWithItems}{wxcontrolwithitems} +interface. + +Implementing item drawing and measuring is similar to \helpref{wxVListBox}{wxvlistbox}. +Application needs to subclass wxOwnerDrawnComboBox and implement +\helpref{OnDrawItem()}{wxownerdrawncomboboxondrawitem}, \helpref{OnMeasureItem()}{wxownerdrawncomboboxonmeasureitem} +and \helpref{OnMeasureItemWidth()}{wxownerdrawncomboboxonmeasureitemwidth}. + + +\wxheading{Derived from} + +\helpref{wxComboCtrl}{wxcomboctrl}\\ +\helpref{wxControlWithItems}{wxcontrolwithitems}\\ +\helpref{wxControl}{wxcontrol}\\ +\helpref{wxWindow}{wxwindow}\\ +\helpref{wxEvtHandler}{wxevthandler}\\ +\helpref{wxObject}{wxobject} + +\wxheading{Include files} + + + +\wxheading{Window styles} + +\begin{twocollist}\itemsep=0pt +\twocolitem{\windowstyle{wxODCB\_DCLICK\_CYCLES}}{Double-clicking cycles item +if wxCB\_READONLY is also used. Synonymous with wxCC\_SPECIAL\_DCLICK.} +\twocolitem{\windowstyle{wxODCB\_STD\_CONTROL\_PAINT}}{Control itself is not +custom painted using OnDrawItem. Even if this style is not used, writable +wxOwnerDrawnComboBox is never custom painted unless SetCustomPaintWidth is +called.} +\end{twocollist} + +See also \helpref{wxComboCtrl window styles}{wxcomboctrl} and +base \helpref{window styles overview}{windowstyles}. + +\wxheading{Event handling} + +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event, +when an item on the list is selected. Note that calling +\helpref{GetValue}{wxcomboctrlgetvalue} returns the new value of selection.} +\end{twocollist} + +See also events emitted by \helpref{wxComboCtrl}{wxcomboctrl}. + +\wxheading{See also} + +\helpref{wxComboCtrl}{wxcomboctrl}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxVListBox}{wxvlistbox}, +\rtfsp\helpref{wxCommandEvent}{wxcommandevent} + + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}\label{wxownerdrawncomboboxctor} + +\func{}{wxOwnerDrawnComboBox}{\void} + +Default constructor. + +\func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp +\param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp +\param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp +\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}} + +\func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp +\param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp +\param{const wxArrayString\& }{choices},\rtfsp +\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}} + +Constructor, creating and showing a owner-drawn combobox. + +\wxheading{Parameters} + +\docparam{parent}{Parent window. Must not be NULL.} + +\docparam{id}{Window identifier. A value of -1 indicates a default value.} + +\docparam{value}{Initial selection string. An empty string indicates no selection.} + +\docparam{pos}{Window position.} + +\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized +appropriately.} + +\docparam{n}{Number of strings with which to initialise the control.} + +\docparam{choices}{An array of strings with which to initialise the control.} + +\docparam{style}{Window style. See \helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}.} + +\docparam{validator}{Window validator.} + +\docparam{name}{Window name.} + +\wxheading{See also} + +\helpref{wxOwnerDrawnComboBox::Create}{wxownerdrawncomboboxcreate}, \helpref{wxValidator}{wxvalidator} + + +\membersection{wxOwnerDrawnComboBox::\destruct{wxOwnerDrawnComboBox}}\label{wxownerdrawncomboboxdtor} + +\func{}{\destruct{wxOwnerDrawnComboBox}}{\void} + +Destructor, destroying the owner-drawn combobox. + + +\membersection{wxOwnerDrawnComboBox::Create}\label{wxownerdrawncomboboxcreate} + +\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp +\param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp +\param{int}{ n}, \param{const wxString }{choices[]},\rtfsp +\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}} + +\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp +\param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp +\param{const wxArrayString\& }{choices},\rtfsp +\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}} + +Creates the combobox for two-step construction. Derived classes +should call or replace this function. See +\helpref{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}{wxownerdrawncomboboxctor}\rtfsp +for further details. + + +\membersection{wxOwnerDrawnComboBox::OnDrawBackground}\label{wxownerdrawncomboboxondrawbackground} + +\constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}} + +This method is used to draw the items background and, maybe, a border around it. + +The base class version implements a reasonable default behaviour which consists +in drawing the selected item with the standard background colour and drawing a +border around the item if it is either selected or current. + +\wxheading{Remarks} + +\arg{flags} has the same meaning as with \helpref{OnDrawItem}{wxownerdrawncomboboxondrawitem}. + + +\membersection{wxOwnerDrawnComboBox::OnDrawItem}\label{wxownerdrawncomboboxondrawitem} + +\constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}} + +The derived class may implement this function to actually draw the item +with the given index on the provided DC. If function is not implemented, +the item text is simply drawn, as if the control was a normal combobox. + +\wxheading{Parameters} + +\docparam{dc}{The device context to use for drawing} + +\docparam{rect}{The bounding rectangle for the item being drawn (DC clipping +region is set to this rectangle before calling this function)} + +\docparam{item}{The index of the item to be drawn} + +\docparam{flags}{Combines any of the following flag values:} + +\twocolwidtha{7cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{{\tt wxODCB\_PAINTING\_CONTROL}}{Combo control is being +painted, instead of a list item. Argument item may be wxNOT\_FOUND in this +case.} +\end{twocollist} + + +\membersection{wxOwnerDrawnComboBox::OnMeasureItem}\label{wxownerdrawncomboboxonmeasureitem} + +\constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{item}} + +The derived class may implement this method to return the height of the +specified item (in pixels). + +The default implementation returns text height, as if this control was +a normal combobox. + + +\membersection{wxOwnerDrawnComboBox::OnMeasureItemWidth}\label{wxownerdrawncomboboxonmeasureitemwidth} + +\constfunc{wxCoord}{OnMeasureItemWidth}{\param{size\_t }{item}} + +The derived class may implement this method to return the width of the +specified item (in pixels). If -1 is returned, then the item text width +is used. + +The default implementation returns -1. -- 2.45.2