Kross

form.h
1 /***************************************************************************
2  * form.h
3  * This file is part of the KDE project
4  * copyright (C)2006-2007 by Sebastian Sauer ([email protected])
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Library General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Library General Public License for more details.
14  * You should have received a copy of the GNU Library General Public License
15  * along with this program; see the file COPYING. If not, write to
16  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18  ***************************************************************************/
19 
20 #ifndef KROSS_FORM_H
21 #define KROSS_FORM_H
22 
23 #include <QWidget>
24 #include <QUrl>
25 #include <QListWidget>
26 
27 #include <kpagedialog.h>
28 #include <kassistantdialog.h>
29 //#include <kfilewidget.h>
30 
31 class QAbstractButton;
32 
33 namespace Kross
34 {
35 
36 /**
37  * The FormListView class provides access to a ListView.
38  */
39 class FormListView : public QListWidget
40 {
41  Q_OBJECT
42 public:
43  explicit FormListView(QWidget *parent);
44  ~FormListView() override;
45 public Q_SLOTS:
46  void clear();
47  void remove(int index);
48  void addItem(const QString &text);
49  int count();
50  int current();
51  void setCurrent(int row);
52  QString text(int row);
53 };
54 
55 /**
56  * The FormFileWidget class provides access to a KFileWidget.
57  */
58 class FormFileWidget : public QWidget
59 {
60  Q_OBJECT
61  Q_ENUMS(Mode)
62 
63 public:
64  FormFileWidget(QWidget *parent, const QString &startDirOrVariable);
65  ~FormFileWidget() override;
66 
67  /**
68  * The Mode the FormFileWidget could have.
69  */
70  enum Mode { Other = 0, Opening, Saving };
71 
72 public Q_SLOTS:
73 
74  /**
75  * Set the \a Mode the FormFileWidget should have to \p mode .
76  * Valid modes are "Other", "Opening" or "Saving".
77  */
78  void setMode(const QString &mode);
79 
80  /**
81  * \return the current filter.
82  */
83  QString currentFilter() const;
84 
85  /**
86  * Set the filter to \p filter .
87  */
88  void setFilter(const QString &filter);
89 
90  /**
91  * \return the current mimetype filter.
92  */
93  QString currentMimeFilter() const;
94 
95  /**
96  * Set the mimetype filter to \p filter .
97  */
98  void setMimeFilter(const QStringList &filter);
99 
100  /**
101  * \return the currently selected file.
102  */
103  QString selectedFile() const;
104 
105  //QStringList selectedFiles() const { return KFileDialog::selectedFiles(); }
106  //QString selectedUrl() const { return KFileDialog::selectedUrl().toLocalFile(); }
107 
108 Q_SIGNALS:
109 
110  /**
111  * Emitted when the user selects a file. It is only emitted in single-
112  * selection mode.
113  */
114  void fileSelected(const QString &file);
115 
116  /**
117  * Emitted when the user highlights a file.
118  */
119  void fileHighlighted(const QString &);
120 
121  /**
122  * Emitted when the user highlights one or more files in multiselection mode.
123  */
124  void selectionChanged();
125 
126  /**
127  * Emitted when the filter changed, i.e. the user entered an own filter
128  * or chose one of the predefined set via setFilter().
129  */
130  void filterChanged(const QString &filter);
131 
132 private Q_SLOTS:
133  void slotFileSelected(const QUrl &);
134  void slotFileHighlighted(const QUrl &);
135 
136 private:
137  /// \internal d-pointer class.
138  class Private;
139  /// \internal d-pointer instance.
140  Private *const d;
141 };
142 
143 /**
144  * The FormProgressDialog class provides access to progressbar.
145  *
146  * Example (in Python) :
147  * \code
148  * import time, Kross
149  * forms = Kross.module("forms")
150  * progress = forms.showProgressDialog("My Title")
151  * progress.setText("Some <i>detailed</i> text.")
152  * for i in range(0,101):
153  * progress.setValue(i)
154  * progress.addText("%s" % i)
155  * time.sleep(1)
156  * progress.reset()
157  * \endcode
158  */
160 {
161  Q_OBJECT
162 public:
163  FormProgressDialog(const QString &caption, const QString &labelText);
164  ~FormProgressDialog() override;
165  void done(int r) override;
166 public Q_SLOTS:
167  /**
168  * Set the value of the progressbar. If -1 the progressbar will be hidden.
169  */
170  void setValue(int progress);
171  /**
172  * Set the minimum and maximum range of the progressbar.
173  */
174  void setRange(int minimum, int maximum);
175  /**
176  * Set the HTML-text that is displayed as information to the text \p text .
177  */
178  void setText(const QString &text);
179  /**
180  * Add to the HTML-text that is displayed as information the text \p text .
181  */
182  void addText(const QString &text);
183  /**
184  * Shows the dialog as a modal dialog, blocking until the user
185  * closes it and returns the execution result.
186  *
187  * \return >=1 if the dialog was accepted (e.g. "Ok" pressed) else
188  * the user rejected the dialog (e.g. by pressing "Cancel" or just
189  * closing the dialog by pressing the escape-key).
190  */
191  int exec() override;
192  /**
193  * Same as the \a exec() method above provided for Python-lovers (python
194  * does not like functions named "exec" and PyQt named it "exec_loop", so
195  * just let's do the same).
196  */
197  int exec_loop()
198  {
199  return exec();
200  }
201  /**
202  * Returns true if the user requested to cancel the operation.
203  */
204  bool isCanceled();
205 Q_SIGNALS:
206  /**
207  * This signal got emitted if the user requests to cancel the operation.
208  */
209  void canceled();
210 private:
211  /// \internal d-pointer class.
212  class Private;
213  /// \internal d-pointer instance.
214  Private *const d;
215 };
216 
217 /**
218  * The FormDialog class provides access to KPageDialog objects as
219  * top-level containers.
220  *
221  * Example (in Python) :
222  * \code
223  * import Kross
224  * import sys,os
225  * ourPath=(filter(lambda p: os.path.exists(p+'/mywidget.ui'),sys.path)+[''])[0]
226  * forms = Kross.module("forms")
227  * mydialog = forms.createDialog("MyDialog")
228  * mydialog.setButtons("Ok|Cancel")
229  * mydialog.setFaceType("Plain") #Auto Plain List Tree Tabbed
230  * mypage = mydialog.addPage("name","header")
231  * mywidget = forms.createWidgetFromUIFile(mypage, ourPath+'/mywidget.ui')
232  * mywidget["lineEdit"].setText("some string")
233  * if mydialog.exec_loop():
234  * if mydialog.result() == "Ok":
235  * print mywidget["lineEdit"].text
236  * mydialog.deleteLater()
237  * \endcode
238  */
239 class FormDialog: public KPageDialog
240 {
241  Q_OBJECT
242 
243 public:
244  FormDialog(const QString &caption);
245  ~FormDialog() override;
246 
247 public Q_SLOTS:
248 
249  /**
250  * Set the buttons.
251  *
252  * \param buttons string that defines the displayed buttons. For example the
253  * string may look like "Ok" or "Ok|Cancel" or "Yes|No|Cancel".
254  * \return true if the passed \p buttons string was valid and setting the
255  * buttons was successfully else false is returned.
256  */
257  bool setButtons(const QString &buttons);
258 
259  /**
260  * Set the text of a button.
261  *
262  * Sample how to change the buttons of a dialog;
263  * \code
264  * dialog.setButtons("Yes|No|Cancel")
265  * dialog.setButtonText("Yes","Overwrite")
266  * dialog.setButtonText("No","Skip")
267  * dialog.setButtonText("Cancel","Abort")
268  * \endcode
269  *
270  * \param button string that defines the button that should be changed.
271  * \param text string that should be used as button text.
272  * \return true if the passed \p buttons string was valid and setting the
273  * button text was successfully else false is returned.
274  */
275  bool setButtonText(const QString &button, const QString &text);
276 
277  /**
278  * Set the face type of the dialog.
279  *
280  * \param facetype the face type which could be "Auto", "Plain", "List",
281  * "Tree" or "Tabbed" as defined in \a KPageView::FaceType .
282  */
283  bool setFaceType(const QString &facetype);
284 
285  /**
286  * \return the name of the currently selected page. Use the \a page()
287  * method to get the matching page QWidget instance.
288  */
289  QString currentPage() const;
290 
291  /**
292  * Set the current page to \p name . If there exists no page with
293  * such a pagename the method returns false else (if the page was
294  * successfully set) true is returned.
295  */
296  bool setCurrentPage(const QString &name);
297 
298  /**
299  * \return the QWidget page instance which has the pagename \p name
300  * or NULL if there exists no such page.
301  */
302  QWidget *page(const QString &name) const;
303 
304  /**
305  * Add and return a new page.
306  *
307  * \param name The name the page has. This name is for example returned
308  * at the \a currentPage() method and should be unique. The name is also
309  * used to display a short title for the page.
310  * \param header The longer header title text used for display purposes.
311  * \param iconname The name of the icon which the page have. This could
312  * be for example "about_kde", "document-open", "configure" or any other
313  * iconname known by KDE.
314  * \return the new QWidget page instance.
315  */
316  QWidget *addPage(const QString &name, const QString &header = QString(), const QString &iconname = QString());
317 
318  /**
319  * Shows the dialog as a modal dialog, blocking until the user
320  * closes it and returns the execution result.
321  *
322  * \return >=1 if the dialog was accepted (e.g. "Ok" pressed) else
323  * the user rejected the dialog (e.g. by pressing "Cancel" or just
324  * closing the dialog by pressing the escape-key).
325  */
326  int exec() override
327  {
328  return QDialog::exec();
329  }
330 
331  /**
332  * Same as the \a exec() method above provided for Python-lovers (python
333  * does not like functions named "exec" and PyQt named it "exec_loop", so
334  * just let's do the same).
335  */
336  int exec_loop()
337  {
338  return exec();
339  }
340 
341  /**
342  * \return the result. The result may for example "Ok", "Cancel", "Yes" or "No".
343  */
344  QString result();
345 
346 private Q_SLOTS:
347  virtual void slotButtonClicked(QAbstractButton *button);
348  void slotCurrentPageChanged(KPageWidgetItem *current);
349 
350 private:
351  /// \internal d-pointer class.
352  class Private;
353  /// \internal d-pointer instance.
354  Private *const d;
355 };
356 
357 /**
358  * The FormAssistant class provides access to KAssistantDialog objects as
359  * top-level containers.
360  *
361  * Example (in Python) :
362  * \code
363  * import Kross
364  * import sys,os
365  * ourPath=(filter(lambda p: os.path.exists(p+'/mywidget.ui'),sys.path)+[''])[0]
366  * forms = Kross.module("forms")
367  * myassistant = forms.createAssistant("MyAssistant")
368  * myassistant.showHelpButton(0)
369  * mypage = myassistant.addPage("name","header")
370  * mywidget = forms.createWidgetFromUIFile(mypage, ourPath+'/mywidget.ui')
371  * mypage2 = myassistant.addPage("name2","header2")
372  * mywidget2 = forms.createWidgetFromUIFile(mypage2, ourPath+'/mywidget.ui')
373  * mypage3 = myassistant.addPage("name3","header3")
374  * mywidget3 = forms.createWidgetFromUIFile(mypage3, ourPath+'/mywidget.ui')
375  * mywidget["lineEdit"].setText("some string")
376  *
377  * def nextClicked():
378  * myassistant.setAppropriate("name2",0)
379  * def finished():
380  * ...
381  * myassistant.deleteLater() #remember to cleanup
382  *
383  * myassistant.connect("nextClicked()",nextClicked)
384  * myassistant.connect("finished()",finished)
385  * myassistant.show()
386  *
387  * \endcode
388  */
390 {
391  Q_OBJECT
392  Q_ENUMS(AssistantButtonCode)
393 public:
394  enum AssistantButtonCode {
395  None = 0x00000000,
396  Help = 0x00000001,
397  Default = 0x00000002,
398  Cancel = 0x00000020,
399  Finish = 0x00001000,
400  Next = 0x00002000,
401  Back = 0x00004000,
402  NoDefault = 0x00008000
403  };
404  Q_DECLARE_FLAGS(AssistantButtonCodes, AssistantButtonCode)
405 
406 public:
407  FormAssistant(const QString &caption);
408  ~FormAssistant() override;
409 
410 public Q_SLOTS:
411 
412  void showHelpButton(bool);
413 
414  /**
415  * \return the name of the currently selected page. Use the \a page()
416  * method to get the matching page QWidget instance.
417  */
418  QString currentPage() const;
419 
420  /**
421  * Set the current page to \p name . If there exists no page with
422  * such a pagename the method returns false else (if the page was
423  * successfully set) true is returned.
424  */
425  bool setCurrentPage(const QString &name);
426 
427  /**
428  * \return the QWidget page instance which has the pagename \p name
429  * or NULL if there exists no such page.
430  */
431  QWidget *page(const QString &name) const;
432 
433  /**
434  * Add and return a new page.
435  *
436  * \param name The name the page has. This name is for example returned
437  * at the \a currentPage() method and should be unique. The name is also
438  * used to display a short title for the page.
439  * \param header The longer header title text used for display purposes.
440  * \param iconname The name of the icon which the page have. This could
441  * be for example "about_kde", "document-open", "configure" or any other
442  * iconname known by KDE.
443  * \return the new QWidget page instance.
444  */
445  QWidget *addPage(const QString &name, const QString &header = QString(), const QString &iconname = QString());
446 
447  /**
448  * @see KAssistantDialog::isAppropriate()
449  */
450  bool isAppropriate(const QString &name) const;
451  /**
452  * @see KAssistantDialog::setAppropriate()
453  */
454  void setAppropriate(const QString &name, bool appropriate);
455  /**
456  * @see KAssistantDialog::isValid()
457  */
458  bool isValid(const QString &name) const;
459  /**
460  * @see KAssistantDialog::setValid()
461  */
462  void setValid(const QString &name, bool enable);
463 
464  /**
465  * Shows the dialog as a modal dialog, blocking until the user
466  * closes it and returns the execution result.
467  *
468  * \return >=1 if the dialog was accepted (e.g. "Finished" pressed) else
469  * the user rejected the dialog (e.g. by pressing "Cancel" or just
470  * closing the dialog by pressing the escape-key).
471  */
472  int exec() override
473  {
474  return QDialog::exec();
475  }
476 
477  /**
478  * Same as the \a exec() method above provided for Python-lovers (python
479  * does not like functions named "exec" and PyQt named it "exec_loop", so
480  * just let's do the same).
481  */
482  int exec_loop()
483  {
484  return exec();
485  }
486 
487  /**
488  * \return the result. The result may for example "Finish" or "Cancel".
489  */
490  QString result();
491 
492  /**
493  * Force page switching. This will also emit backClicked()
494  */
495  void back() override;
496  /**
497  * Force page switching. This will also emit nextClicked()
498  */
499  void next() override;
500 
501 private Q_SLOTS:
502  virtual void slotButtonClicked(QAbstractButton *button);
503  void slotCurrentPageChanged(KPageWidgetItem *current);
504 
505 Q_SIGNALS:
506  /**
507  * use it to setAppropriate()
508  */
509  void nextClicked();
510  void backClicked();
511 
512 private:
513  /// \internal d-pointer class.
514  class Private;
515  /// \internal d-pointer instance.
516  Private *const d;
517 };
518 
519 /**
520  * The FormModule provides access to UI functionality like dialogs or widgets.
521  *
522  * Example (in Python) :
523  * \code
524  * import Kross
525  * forms = Kross.module("forms")
526  * dialog = forms.createDialog("My Dialog")
527  * dialog.setButtons("Ok|Cancel")
528  * page = dialog.addPage("Welcome","Welcome Page","document-open")
529  * label = forms.createWidget(page,"QLabel")
530  * label.text = "Hello World Label"
531  * if dialog.exec_loop():
532  * forms.showMessageBox("Information", "Okay...", "The Ok-button was pressed")
533  * \endcode
534  */
535 class FormModule: public QObject
536 {
537  Q_OBJECT
538 
539 public:
540  explicit FormModule();
541  ~FormModule() override;
542 
543 public Q_SLOTS:
544 
545  /**
546  * \return the active modal widget. Modal widgets are special top-level
547  * widgets which are subclasses of QDialog and are modal.
548  */
549  QWidget *activeModalWidget();
550 
551  /**
552  * \return the application top-level window that has the keyboard input
553  * focus, or NULL if no application window has the focus.
554  */
555  QWidget *activeWindow();
556 
557  /**
558  * \return i18n'ed version of the string
559  */
560  QString tr(const QString &str);
561 
562  /**
563  * \return i18n'ed version of the string, differentiated by the comment text (like '\@title:window')
564  */
565  QString tr(const QString &str, const QString &comment);
566 
567  /**
568  * Show a messagebox.
569  *
570  * \param dialogtype The type of the dialog which could be one
571  * of the following;
572  * \li Sorry
573  * \li Error
574  * \li Information
575  * \li QuestionYesNo
576  * \li WarningYesNo
577  * \li WarningContinueCancel
578  * \li WarningYesNoCancel
579  * \li QuestionYesNoCancel
580  * \param caption The caption the messagedialog displays.
581  * \param message The message that is displayed in the messagedialog.
582  * \param details The optional details
583  * \return The buttoncode which could be one of the following;
584  * \li Ok
585  * \li Cancel
586  * \li Yes
587  * \li No
588  * \li Continue
589  */
590  QString showMessageBox(const QString &dialogtype, const QString &caption, const QString &message, const QString &details = QString());
591 
592  /**
593  * Show a progressdialog to provide visible feedback on the progress
594  * of a slow operation.
595  *
596  * \param caption The caption the progressdialog displays.
597  * \param labelText The displayed label.
598  * \return The QProgressDialog widget instance.
599  */
600  QWidget *showProgressDialog(const QString &caption, const QString &labelText);
601 
602  /**
603  * Create and return a new \a FormDialog instance.
604  *
605  * \param caption The displayed caption of the dialog.
606  */
607  QWidget *createDialog(const QString &caption);
608 
609  /**
610  * Create and return a new \a FormAssistant instance.
611  *
612  * \param caption The displayed caption of the dialog.
613  */
614  QWidget *createAssistant(const QString &caption);
615 
616  /**
617  * Create and return a new QWidget instance.
618  *
619  * \param parent the parent QWidget the new QWidget is a child of.
620  * \param layout the layout style the widget has. This could be one
621  * of the following strings;
622  * \li QVBoxLayout
623  * \li QHBoxLayout
624  * \li QStackedLayout
625  * \return the new QLayout instance or NULL.
626  */
627  QObject *createLayout(QWidget *parent, const QString &layout);
628 
629  /**
630  * Create and return a new QWidget instance.
631  *
632  * \param parent the parent QWidget the new QWidget is a child of.
633  * \param className the name of the class that should be created
634  * and returned. For example "QLabel" or "QForm".
635  * \param name the objectName the new widget has.
636  * \return the new QWidget instance or NULL.
637  */
638  QWidget *createWidget(const QString &className);
639 
640  /**
641  * Create and return a new QWidget instance.
642  *
643  * \param parent the parent QWidget the new QWidget is a child of.
644  * \param className the name of the class that should be created
645  * and returned. For example "QLabel" or "QForm".
646  * \param name the objectName the new widget has.
647  * \return the new QWidget instance or NULL.
648  */
649  QWidget *createWidget(QWidget *parent, const QString &className, const QString &name = QString());
650 
651  /**
652  * Create and return a new QWidget instance.
653  *
654  * \param parent the new QWidget is a child of parent.
655  * \param xml the UI XML string used to construct the new widget.
656  * \return the new QWidget instance or NULL.
657  */
658  QWidget *createWidgetFromUI(QWidget *parent, const QString &xml);
659 
660  /**
661  * Create and return a new QWidget instance.
662  *
663  * \param parent the parent QWidget the new QWidget is a child of.
664  * \param filename the full filename of the UI file which is read
665  * and its UI XML content is used to construct the new widget.
666  */
667  QWidget *createWidgetFromUIFile(QWidget *parent, const QString &filename);
668 
669  /**
670  * Create and return a new \a FormFileWidget instance.
671  *
672  * \param parent the parent QWidget the new \a FormFileWidget instance
673  * is a child of.
674  * \param startDirOrVariable the start-directory or -variable.
675  * \return the new \a FormFileWidget instance or NULL.
676  */
677  QWidget *createFileWidget(QWidget *parent, const QString &startDirOrVariable = QString());
678 
679  /**
680  * Create and return a new \a FormListView instance.
681  *
682  * \param parent the parent QWidget the new \a FormListView instance
683  * is a child of.
684  * \return the new \a FormFileWidget instance or NULL.
685  */
686  QWidget *createListView(QWidget *parent);
687 
688  /**
689  * Load and return a KPart component.
690  * \param parent The parent QWidget the KPart's widget will be child of.
691  * \param name The name of the KPart library like e.g. "libkhtmlpart".
692  * \param url Optional Url that should be opened on load.
693  */
694  QObject *loadPart(QWidget *parent, const QString &name, const QUrl &url = QUrl());
695 
696  /**
697  * Create and return a new \a QAction instance.
698  *
699  * \param parent the parent QObject the new \a QAction instance
700  * is a child of.
701  * \return the new \a QAction instance or NULL.
702  */
703  QAction *createAction(QObject *parent);
704 
705 private:
706  /// \internal d-pointer class.
707  class Private;
708  /// \internal d-pointer instance.
709  Private *const d;
710 };
711 }
712 
713 #endif
714 
QLayout * layout() const const
int exec_loop()
Same as the exec() method above provided for Python-lovers (python does not like functions named "exe...
Definition: form.h:336
int exec() override
Shows the dialog as a modal dialog, blocking until the user closes it and returns the execution resul...
Definition: form.h:326
Definition: action.cpp:36
virtual int exec()
The FormFileWidget class provides access to a KFileWidget.
Definition: form.h:58
The FormDialog class provides access to KPageDialog objects as top-level containers.
Definition: form.h:239
Q_SIGNALSQ_SIGNALS
QString tr(const char *sourceText, const char *disambiguation, int n)
int exec_loop()
Same as the exec() method above provided for Python-lovers (python does not like functions named "exe...
Definition: form.h:197
Q_OBJECTQ_OBJECT
int exec() override
Shows the dialog as a modal dialog, blocking until the user closes it and returns the execution resul...
Definition: form.h:472
The FormModule provides access to UI functionality like dialogs or widgets.
Definition: form.h:535
int row(const QListWidgetItem *item) const const
Q_ENUMS(...)
The FormListView class provides access to a ListView.
Definition: form.h:39
The FormProgressDialog class provides access to progressbar.
Definition: form.h:159
Q_SLOTSQ_SLOTS
QObject * parent() const const
Mode
The Mode the FormFileWidget could have.
Definition: form.h:70
virtual void selectionChanged(const QItemSelection &selected, const QItemSelection &deselected) override
int exec_loop()
Same as the exec() method above provided for Python-lovers (python does not like functions named "exe...
Definition: form.h:482
The FormAssistant class provides access to KAssistantDialog objects as top-level containers.
Definition: form.h:389
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Oct 24 2021 22:59:01 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.