Katana_mirror/kdelibs
1
0
Fork 0
mirror of https://bitbucket.org/smil3y/kdelibs.git synced 2025-02-24 10:52:49 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
kdelibs/kross/modules/form.h
Ivailo Monev 814163a8dc initial import
2014-11-13 01:04:59 +02:00

706 lines
25 KiB
C++
Raw Blame History

/***************************************************************************
* form.h
* This file is part of the KDE project
* copyright (C)2006-2007 by Sebastian Sauer (mail@dipe.org)
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
* You should have received a copy of the GNU Library General Public License
* along with this program; see the file COPYING. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
***************************************************************************/
#ifndef KROSS_FORM_H
#define KROSS_FORM_H
#include <QtGui/QWidget>
#include <QtCore/QUrl>
#include <QtGui/QListWidget>
#include <kpagedialog.h>
#include <kassistantdialog.h>
//#include <kfilewidget.h>
namespace Kross {
/**
* The FormListView class provides access to a ListView.
*/
class FormListView : public QListWidget
{
Q_OBJECT
public:
explicit FormListView(QWidget* parent);
virtual ~FormListView();
public Q_SLOTS:
void clear();
void remove(int index);
void addItem(const QString& text);
int count();
int current();
void setCurrent(int row);
QString text(int row);
};
/**
* The FormFileWidget class provides access to a KFileWidget.
*/
class FormFileWidget : public QWidget
{
Q_OBJECT
Q_ENUMS(Mode)
public:
FormFileWidget(QWidget* parent, const QString& startDirOrVariable);
virtual ~FormFileWidget();
/**
* The Mode the FormFileWidget could have.
*/
enum Mode { Other = 0, Opening, Saving };
public Q_SLOTS:
/**
* Set the \a Mode the FormFileWidget should have to \p mode .
* Valid modes are "Other", "Opening" or "Saving".
*/
void setMode(const QString& mode);
/**
* \return the current filter.
*/
QString currentFilter() const;
/**
* Set the filter to \p filter .
*/
void setFilter(const QString &filter);
/**
* \return the current mimetype filter.
*/
QString currentMimeFilter() const;
/**
* Set the mimetype filter to \p filter .
*/
void setMimeFilter(const QStringList& filter);
/**
* \return the currently selected file.
*/
QString selectedFile() const;
//QStringList selectedFiles() const { return KFileDialog::selectedFiles(); }
//QString selectedUrl() const { return KFileDialog::selectedUrl().toLocalFile(); }
Q_SIGNALS:
/**
* Emitted when the user selects a file. It is only emitted in single-
* selection mode.
*/
void fileSelected(const QString& file);
/**
* Emitted when the user highlights a file.
*/
void fileHighlighted(const QString&);
/**
* Emitted when the user hilights one or more files in multiselection mode.
*/
void selectionChanged();
/**
* Emitted when the filter changed, i.e. the user entered an own filter
* or chose one of the predefined set via setFilter().
*/
void filterChanged(const QString& filter);
private Q_SLOTS:
void slotFileSelected(const QString&);
private:
/// \internal d-pointer class.
class Private;
/// \internal d-pointer instance.
Private* const d;
};
/**
* The FormProgressDialog class provides access to progressbar.
*
* Example (in Python) :
* \code
* import time, Kross
* forms = Kross.module("forms")
* progress = forms.showProgressDialog("My Title")
* progress.setText("Some <i>detailed</i> text.")
* for i in range(0,101):
* progress.setValue(i)
* progress.addText("%s" % i)
* time.sleep(1)
* progress.reset()
* \endcode
*/
class FormProgressDialog : public KPageDialog
{
Q_OBJECT
public:
FormProgressDialog(const QString& caption, const QString& labelText);
virtual ~FormProgressDialog();
virtual void done(int r);
public Q_SLOTS:
/**
* Set the value of the progressbar. If -1 the progressbar will be hidden.
*/
void setValue(int progress);
/**
* Set the minimum and maximum range of the progressbar.
*/
void setRange(int minimum, int maximum);
/**
* Set the HTML-text that is displayed as information to the text \p text .
*/
void setText(const QString& text);
/**
* Add to the HTML-text that is displayed as information the text \p text .
*/
void addText(const QString& text);
/**
* Shows the dialog as a modal dialog, blocking until the user
* closes it and returns the execution result.
*
* \return >=1 if the dialog was accepted (e.g. "Ok" pressed) else
* the user rejected the dialog (e.g. by pressing "Cancel" or just
* closing the dialog by pressing the escape-key).
*/
int exec();
/**
* Same as the \a exec() method above provided for Python-lovers (python
* does not like functions named "exec" and PyQt named it "exec_loop", so
* just let's do the same).
*/
int exec_loop() { return exec(); }
/**
* Returns true if the user requested to cancel the operation.
*/
bool isCanceled();
Q_SIGNALS:
/**
* This signal got emitted if the user requests to cancel the operation.
*/
void canceled();
private:
/// \internal d-pointer class.
class Private;
/// \internal d-pointer instance.
Private* const d;
};
/**
* The FormDialog class provides access to KDialog objects as
* top-level containers.
*
* Example (in Python) :
* \code
* import Kross
* import sys,os
* ourPath=(filter(lambda p: os.path.exists(p+'/mywidget.ui'),sys.path)+[''])[0]
* forms = Kross.module("forms")
* mydialog = forms.createDialog("MyDialog")
* mydialog.setButtons("Ok|Cancel")
* mydialog.setFaceType("Plain") #Auto Plain List Tree Tabbed
* mypage = mydialog.addPage("name","header")
* mywidget = forms.createWidgetFromUIFile(mypage, ourPath+'/mywidget.ui')
* mywidget["lineEdit"].setText("some string")
* if mydialog.exec_loop():
* if mydialog.result() == "Ok":
* print mywidget["lineEdit"].text
* mydialog.deleteLater()
* \endcode
*/
class FormDialog: public KPageDialog
{
Q_OBJECT
public:
FormDialog(const QString& caption);
virtual ~FormDialog();
public Q_SLOTS:
/**
* Set the buttons.
*
* \param buttons string that defines the displayed buttons. For example the
* string may look like "Ok" or "Ok|Cancel" or "Yes|No|Cancel".
* \return true if the passed \p buttons string was valid and setting the
* buttons was successfully else false is returned.
*/
bool setButtons(const QString& buttons);
/**
* Set the text of a button.
*
* Sample how to change the buttons of a dialog;
* \code
* dialog.setButtons("Yes|No|Cancel")
* dialog.setButtonText("Yes","Overwrite")
* dialog.setButtonText("No","Skip")
* dialog.setButtonText("Cancel","Abort")
* \endcode
*
* \param button string that defines the button that should be changed.
* \param text string that should be used as button text.
* \return true if the passed \p buttons string was valid and setting the
* button text was successfully else false is returned.
*/
bool setButtonText(const QString& button, const QString& text);
/**
* Set the face type of the dialog.
*
* \param facetype the face type which could be "Auto", "Plain", "List",
* "Tree" or "Tabbed" as defined in \a KPageView::FaceType .
*/
bool setFaceType(const QString& facetype);
/**
* \return the name of the currently selected page. Use the \a page()
* method to get the matching page QWidget instance.
*/
QString currentPage() const;
/**
* Set the current page to \p name . If there exists no page with
* such a pagename the method returns false else (if the page was
* successfully set) true is returned.
*/
bool setCurrentPage(const QString& name);
/**
* \return the QWidget page instance which has the pagename \p name
* or NULL if there exists no such page.
*/
QWidget* page(const QString& name) const;
/**
* Add and return a new page.
*
* \param name The name the page has. This name is for example returned
* at the \a currentPage() method and should be unique. The name is also
* used to display a short title for the page.
* \param header The longer header title text used for display purposes.
* \param iconname The name of the icon which the page have. This could
* be for example "about_kde", "document-open", "configure" or any other
* iconname known by KDE.
* \return the new QWidget page instance.
*/
QWidget* addPage(const QString& name, const QString& header = QString(), const QString& iconname = QString());
/**
* Set the \p newMainWidget QWidget as main widget. This is only needed if
* you like to replace the KPageDialog page-widget with your own widget.
*/
void setMainWidget(QWidget *newMainWidget);
/**
* Shows the dialog as a modal dialog, blocking until the user
* closes it and returns the execution result.
*
* \return >=1 if the dialog was accepted (e.g. "Ok" pressed) else
* the user rejected the dialog (e.g. by pressing "Cancel" or just
* closing the dialog by pressing the escape-key).
*/
int exec() { return KDialog::exec(); }
/**
* Same as the \a exec() method above provided for Python-lovers (python
* does not like functions named "exec" and PyQt named it "exec_loop", so
* just let's do the same).
*/
int exec_loop() { return exec(); }
/**
* \return the result. The result may for example "Ok", "Cancel", "Yes" or "No".
*/
QString result();
private Q_SLOTS:
virtual void slotButtonClicked(int button);
void slotCurrentPageChanged(KPageWidgetItem* current);
private:
/// \internal d-pointer class.
class Private;
/// \internal d-pointer instance.
Private* const d;
};
/**
* The FormAssistant class provides access to KAssistantDialog objects as
* top-level containers.
*
* Example (in Python) :
* \code
* import Kross
* import sys,os
* ourPath=(filter(lambda p: os.path.exists(p+'/mywidget.ui'),sys.path)+[''])[0]
* forms = Kross.module("forms")
* myassistant = forms.createAssistant("MyAssistant")
* myassistant.showHelpButton(0)
* mypage = myassistant.addPage("name","header")
* mywidget = forms.createWidgetFromUIFile(mypage, ourPath+'/mywidget.ui')
* mypage2 = myassistant.addPage("name2","header2")
* mywidget2 = forms.createWidgetFromUIFile(mypage2, ourPath+'/mywidget.ui')
* mypage3 = myassistant.addPage("name3","header3")
* mywidget3 = forms.createWidgetFromUIFile(mypage3, ourPath+'/mywidget.ui')
* mywidget["lineEdit"].setText("some string")
*
* def nextClicked():
* myassistant.setAppropriate("name2",0)
* def finished():
* ...
* myassistant.deleteLater() #remember to cleanup
*
* myassistant.connect("nextClicked()",nextClicked)
* myassistant.connect("finished()",finished)
* myassistant.show()
*
* \endcode
*/
class FormAssistant: public KAssistantDialog
{
Q_OBJECT
Q_ENUMS(AssistantButtonCode)
public:
enum AssistantButtonCode
{
None = 0x00000000,
Help = 0x00000001,
Default = 0x00000002,
Cancel = 0x00000020,
Finish = 0x00001000,
Next = 0x00002000,
Back = 0x00004000,
NoDefault = 0x00008000
};
Q_DECLARE_FLAGS(AssistantButtonCodes, AssistantButtonCode)
public:
FormAssistant(const QString& caption);
virtual ~FormAssistant();
public Q_SLOTS:
void showHelpButton(bool);
/**
* \return the name of the currently selected page. Use the \a page()
* method to get the matching page QWidget instance.
*/
QString currentPage() const;
/**
* Set the current page to \p name . If there exists no page with
* such a pagename the method returns false else (if the page was
* successfully set) true is returned.
*/
bool setCurrentPage(const QString& name);
/**
* \return the QWidget page instance which has the pagename \p name
* or NULL if there exists no such page.
*/
QWidget* page(const QString& name) const;
/**
* Add and return a new page.
*
* \param name The name the page has. This name is for example returned
* at the \a currentPage() method and should be unique. The name is also
* used to display a short title for the page.
* \param header The longer header title text used for display purposes.
* \param iconname The name of the icon which the page have. This could
* be for example "about_kde", "document-open", "configure" or any other
* iconname known by KDE.
* \return the new QWidget page instance.
*/
QWidget* addPage(const QString& name, const QString& header = QString(), const QString& iconname = QString());
/**
* @see KAssistantDialog::isAppropriate()
*/
bool isAppropriate (const QString& name) const;
/**
* @see KAssistantDialog::setAppropriate()
*/
void setAppropriate (const QString& name, bool appropriate);
/**
* @see KAssistantDialog::isValid()
*/
bool isValid (const QString& name) const;
/**
* @see KAssistantDialog::setValid()
*/
void setValid (const QString& name, bool enable);
/**
* Shows the dialog as a modal dialog, blocking until the user
* closes it and returns the execution result.
*
* \return >=1 if the dialog was accepted (e.g. "Finished" pressed) else
* the user rejected the dialog (e.g. by pressing "Cancel" or just
* closing the dialog by pressing the escape-key).
*/
int exec() { return KDialog::exec(); }
/**
* Same as the \a exec() method above provided for Python-lovers (python
* does not like functions named "exec" and PyQt named it "exec_loop", so
* just let's do the same).
*/
int exec_loop() { return exec(); }
/**
* \return the result. The result may for example "Finish" or "Cancel".
*/
QString result();
/**
* Force page switching. This will also emit backClicked()
*/
void back();
/**
* Force page switching. This will also emit nextClicked()
*/
void next();
private Q_SLOTS:
virtual void slotButtonClicked(int button);
void slotCurrentPageChanged(KPageWidgetItem* current);
signals:
/**
* use it to setAppropriate()
*/
void nextClicked();
void backClicked();
private:
/// \internal d-pointer class.
class Private;
/// \internal d-pointer instance.
Private* const d;
};
/**
* The FormModule provides access to UI functionality like dialogs or widgets.
*
* Example (in Python) :
* \code
* import Kross
* forms = Kross.module("forms")
* dialog = forms.createDialog("My Dialog")
* dialog.setButtons("Ok|Cancel")
* page = dialog.addPage("Welcome","Welcome Page","document-open")
* label = forms.createWidget(page,"QLabel")
* label.text = "Hello World Label"
* if dialog.exec_loop():
* forms.showMessageBox("Information", "Okay...", "The Ok-button was pressed")
* \endcode
*/
class FormModule: public QObject
{
Q_OBJECT
public:
explicit FormModule();
virtual ~FormModule();
public Q_SLOTS:
/**
* \return the active modal widget. Modal widgets are special top-level
* widgets which are subclasses of QDialog and are modal.
*/
QWidget* activeModalWidget();
/**
* \return the application top-level window that has the keyboard input
* focus, or NULL if no application window has the focus.
*/
QWidget* activeWindow();
/**
* \return i18n'ed version of the string
*/
QString tr(const QString& str);
/**
* \return i18n'ed version of the string, differentiated by the comment text (like '\@title:window')
*/
QString tr(const QString& str,const QString& comment);
/**
* Show a messagebox.
*
* \param dialogtype The type of the dialog which could be one
* of the following;
* \li Sorry
* \li Error
* \li Information
* \li QuestionYesNo
* \li WarningYesNo
* \li WarningContinueCancel
* \li WarningYesNoCancel
* \li QuestionYesNoCancel
* \param caption The caption the messagedialog displays.
* \param message The message that is displayed in the messagedialog.
* \param details The optional details
* \return The buttoncode which chould be one of the following;
* \li Ok
* \li Cancel
* \li Yes
* \li No
* \li Continue
*/
QString showMessageBox(const QString& dialogtype, const QString& caption, const QString& message, const QString& details = QString());
/**
* Show a progressdialog to provide visible feedback on the progress
* of a slow operation.
*
* \param caption The caption the progressdialog displays.
* \param labelText The displayed label.
* \return The QProgressDialog widget instance.
*/
QWidget* showProgressDialog(const QString& caption, const QString& labelText);
/**
* Create and return a new \a FormDialog instance.
*
* \param caption The displayed caption of the dialog.
*/
QWidget* createDialog(const QString& caption);
/**
* Create and return a new \a FormAssistant instance.
*
* \param caption The displayed caption of the dialog.
*/
QWidget* createAssistant(const QString& caption);
/**
* Create and return a new QWidget instance.
*
* \param parent the parent QWidget the new QWidget is a child of.
* \param layout the layout style the widget has. This could be one
* of the following strings;
* \li QVBoxLayout
* \li QHBoxLayout
* \li QStackedLayout
* \return the new QLayout instance or NULL.
*/
QObject* createLayout(QWidget* parent, const QString& layout);
/**
* Create and return a new QWidget instance.
*
* \param parent the parent QWidget the new QWidget is a child of.
* \param className the name of the class that should be created
* and returned. For example "QLabel" or "QForm".
* \param name the objectName the new widget has.
* \return the new QWidget instance or NULL.
*/
QWidget* createWidget(const QString& className);
/**
* Create and return a new QWidget instance.
*
* \param parent the parent QWidget the new QWidget is a child of.
* \param className the name of the class that should be created
* and returned. For example "QLabel" or "QForm".
* \param name the objectName the new widget has.
* \return the new QWidget instance or NULL.
*/
QWidget* createWidget(QWidget* parent, const QString& className, const QString& name = QString());
/**
* Create and return a new QWidget instance.
*
* \param parent the new QWidget is a child of parent.
* \param xml the UI XML string used to construct the new widget.
* \return the new QWidget instance or NULL.
*/
QWidget* createWidgetFromUI(QWidget* parent, const QString& xml);
/**
* Create and return a new QWidget instance.
*
* \param parent the parent QWidget the new QWidget is a child of.
* \param filename the full filename of the UI file which is readed
* and its UI XML content is used to construct the new widget.
*/
QWidget* createWidgetFromUIFile(QWidget* parent, const QString& filename);
/**
* Create and return a new \a FormFileWidget instance.
*
* \param parent the parent QWidget the new \a FormFileWidget instance
* is a child of.
* \param startDirOrVariable the start-directory or -variable.
* \return the new \a FormFileWidget instance or NULL.
*/
QWidget* createFileWidget(QWidget* parent, const QString& startDirOrVariable = QString());
/**
* Create and return a new \a FormListView instance.
*
* \param parent the parent QWidget the new \a FormListView instance
* is a child of.
* \return the new \a FormFileWidget instance or NULL.
*/
QWidget* createListView(QWidget* parent);
/**
* Load and return a KPart component.
* \param parent The parent QWidget the KPart's widget will be child of.
* \param name The name of the KPart library like e.g. "libkhtmlpart".
* \param url Optional Url that should be opened on load.
*/
QObject* loadPart(QWidget* parent, const QString& name, const QUrl& url = QUrl());
/**
* Create and return a new \a QAction instance.
*
* \param parent the parent QObject the new \a QAction instance
* is a child of.
* \return the new \a QAction instance or NULL.
*/
QAction* createAction(QObject* parent);
private:
/// \internal d-pointer class.
class Private;
/// \internal d-pointer instance.
Private* const d;
};
}
#endif
Reference in a new issue View git blame Copy permalink