[rkward-cvs] SF.net SVN: rkward: [769] trunk/rkward
tfry at users.sourceforge.net
tfry at users.sourceforge.net
Wed Sep 27 15:28:23 UTC 2006
Revision: 769
http://svn.sourceforge.net/rkward/?rev=769&view=rev
Author: tfry
Date: 2006-09-27 08:28:11 -0700 (Wed, 27 Sep 2006)
Log Message:
-----------
API documentation, small cleanups
Modified Paths:
--------------
trunk/rkward/ChangeLog
trunk/rkward/TODO
trunk/rkward/rkward/windows/detachedwindowcontainer.h
trunk/rkward/rkward/windows/rkmdiwindow.cpp
trunk/rkward/rkward/windows/rkmdiwindow.h
trunk/rkward/rkward/windows/rkworkplace.h
trunk/rkward/rkward/windows/rkworkplaceview.h
Modified: trunk/rkward/ChangeLog
===================================================================
--- trunk/rkward/ChangeLog 2006-09-27 14:06:38 UTC (rev 768)
+++ trunk/rkward/ChangeLog 2006-09-27 15:28:11 UTC (rev 769)
@@ -1,6 +1,6 @@
- internal cleanups (partially to make porting to KDE4/Qt4 easier)
- when saving/loading the workspace, save / restore all windows (not just data editors)
-- remember workspace filename after saving
+- remember workspace url after save as
- fix a long standing (but hard to trigger) crash while closing data editor window
- fix "Open R Script File" filename ending filter
- add mismatching brace detection to syntax highlighting
Modified: trunk/rkward/TODO
===================================================================
--- trunk/rkward/TODO 2006-09-27 14:06:38 UTC (rev 768)
+++ trunk/rkward/TODO 2006-09-27 15:28:11 UTC (rev 769)
@@ -6,7 +6,7 @@
- start being a bit bolder about RKWard (descriptions, startup notification, etc.)
Bugs:
- - There seems to be a race condition at startup, leading to a crash in doPostInit () in rkward.cpp. (Un-)Fortunately it triggers only rarely, and I have not yet figured out, when it occurs.
+ - There seems to be a race condition at startup, leading to a crash in doPostInit () in rkward.cpp. (Un-)Fortunately it triggers only rarely, and I have not yet figured out, when it occurs. Is this still the case? I've fixed one potential race condition a while ago, and have not seen this crash in a while (2006/09/27)
- "cannot create html package index" when installing package as a regular user (due to R.home ("doc") not writable)
- produce many readline calls (e.g. "for (i in 1:10) readline()") repeatedly and cancel all of them.
- Sometimes only the readine is interrupted, sometimes the whole command (might be R's fault? But works fine in plain R)
Modified: trunk/rkward/rkward/windows/detachedwindowcontainer.h
===================================================================
--- trunk/rkward/rkward/windows/detachedwindowcontainer.h 2006-09-27 14:06:38 UTC (rev 768)
+++ trunk/rkward/rkward/windows/detachedwindowcontainer.h 2006-09-27 15:28:11 UTC (rev 769)
@@ -23,7 +23,7 @@
class RKMDIWindow;
-/** This class can be used host a (part) window detached from the main window. @see RKwardApp::slotDetachWindow ().
+/** This class is used to host a (KPart enabled) window detached from the main window. @see RKWorkplace::detachWindow ().
@author Thomas Friedrichsmeier
*/
@@ -31,10 +31,9 @@
Q_OBJECT
public:
/** constructor.
- at param part_to_capture The part to use to create the GUI in the detached window
- at param widget_to_capture The view to reparent into the detached window */
+ at param widget_to_capture The window to reparent into the detached window */
DetachedWindowContainer (RKMDIWindow *widget_to_capture);
-/** destructor. Usually you don't call this explicitely, but rather delete/close the child view. The DetachedWindowContainer will then self destruct */
+/** destructor. Usually you don't call this explicitely, but rather delete/close the child view. The DetachedWindowContainer will then self destruct via viewDestroyed () */
~DetachedWindowContainer ();
public slots:
@@ -42,9 +41,8 @@
void viewDestroyed (QObject *view);
/** re-attach to the main window */
void slotReattach ();
+/** update own caption, when the window's caption has changed */
void updateCaption (RKMDIWindow *);
-private:
- KParts::Part *part;
};
#endif
Modified: trunk/rkward/rkward/windows/rkmdiwindow.cpp
===================================================================
--- trunk/rkward/rkward/windows/rkmdiwindow.cpp 2006-09-27 14:06:38 UTC (rev 768)
+++ trunk/rkward/rkward/windows/rkmdiwindow.cpp 2006-09-27 15:28:11 UTC (rev 769)
@@ -51,10 +51,4 @@
emit (captionChanged (this));
}
-//virtual
-QWidget *RKMDIWindow::getWindow () {
- RK_TRACE (APP);
- return getPart ()->widget ();
-}
-
#include "rkmdiwindow.moc"
Modified: trunk/rkward/rkward/windows/rkmdiwindow.h
===================================================================
--- trunk/rkward/rkward/windows/rkmdiwindow.h 2006-09-27 14:06:38 UTC (rev 768)
+++ trunk/rkward/rkward/windows/rkmdiwindow.h 2006-09-27 15:28:11 UTC (rev 769)
@@ -48,19 +48,29 @@
RKMDIWindow (QWidget *parent, Type type);
virtual ~RKMDIWindow ();
public:
+/** @returns true, if the window's document was modified (and would need to be saved) */
virtual bool isModified () = 0;
+/** @returns A long / complete caption. Default implementation simply calls shortCaption () */
virtual QString fullCaption ();
+/** @returns A short caption (e.g. only the filename without the path). Default implementation simply calls QWidget::caption () */
virtual QString shortCaption ();
+/** @returns The corresponding KPart for this window */
virtual KParts::Part *getPart () = 0;
+/** This is used in RKWorkplace::saveWorkplace () to save the info about the workplace. Make sure to add corresponding code to RKWorkplace::restoreWorkplace (), so your window(s) get restored when loading a Workspace
+ at returns An internal descriptive string suitable for storage in R. */
virtual QString getRDescription () = 0;
+/** Reimplemented from QWidget::setCaption () to emit the signal captionChanged () when the caption is changed. */
void setCaption (const QString &caption);
- virtual QWidget *getWindow ();
signals:
+/** This signal is emitted, whenever the window caption was changed.
+ at param RKMDIWindow* a pointer to this window */
void captionChanged (RKMDIWindow *);
protected:
friend class RKWorkplace;
+/** type of this window */
Type type;
private:
+/** state of this window (attached / detached). This is set from the RKWorkplace */
State state;
};
Modified: trunk/rkward/rkward/windows/rkworkplace.h
===================================================================
--- trunk/rkward/rkward/windows/rkworkplace.h 2006-09-27 14:06:38 UTC (rev 768)
+++ trunk/rkward/rkward/windows/rkworkplace.h 2006-09-27 15:28:11 UTC (rev 769)
@@ -32,10 +32,8 @@
class RKWorkplaceView;
class RKEditor;
-/** This class (only one instance will probably be around) keeps track of which windows are opened in the
-workplace, which are detached, etc. Will replace RKEditorManager.
-It also provides a QWidget (RKWorkplace::view ()), which actually manages the document windows (only those, so far. I.e. this is a half-replacement for KMdi, which will be gone in KDE 4). Currently layout of the document windows is always tabbed.
-//TODO: move to windows */
+/** This class (only one instance will probably be around) keeps track of which windows are opened in the workplace, which are detached, etc. Also it is responsible for creating and manipulating those windows.
+It also provides a QWidget (RKWorkplace::view ()), which actually manages the document windows (only those, so far. I.e. this is a half-replacement for KMdi, which will be gone in KDE 4). Currently layout of the document windows is always tabbed. */
class RKWorkplace : public QObject, public RCommandReceiver {
Q_OBJECT
public:
@@ -44,49 +42,89 @@
RKWorkplace (QWidget *parent);
~RKWorkplace ();
+/** @returns a pointer to the view of the workplace. Since possibly the workplace layout might change, better not rely on this pointer being valid for long */
RKWorkplaceView *view () { return wview; };
+/** convenience typedef: A list of RKMDIWindow s */
typedef QValueList<RKMDIWindow *> RKWorkplaceObjectList;
+/** Returns a list of all windows in the workplace. */
RKWorkplaceObjectList getObjectList () { return windows; };
/** Attach an already created window. */
void attachWindow (RKMDIWindow *window);
+/** Dettach a window (it is removed from the view (), and placed in a top-level DetachedWindowContainer instead. */
void detachWindow (RKMDIWindow *window);
+/** @returns a pointer to the current window. Detached windows are not considered, only those attached to the workplace(view) */
RKMDIWindow *activeAttachedWindow ();
+/** Activate the given window. TODO: is this needed? Does it work?
+ at param window the window to activate */
void activateWindow (RKMDIWindow *window);
+/** Opens a new script editor
+ at param url URL to load. Default option is to open an empty document
+ at param use_r_highlighting Set R highlighting mode (vs. no highlighting)? Default is yes
+ at param read_only Open the document read only? Default is false, i.e. Read-write
+ at param force_caption Usually the caption is determined from the url of the file. If you specify a non-empty string here, that is used instead.
+ at returns false if a local url could not be opened, true for all remote urls, and on success */
bool openScriptEditor (const KURL &url=KURL (), bool use_r_highlighting=true, bool read_only=false, const QString &force_caption = QString::null);
+/** Opens a new help window, starting at the given url
+ at param url URL to open */
void openHelpWindow (const KURL &url=KURL ());
+/** Opens a new output window. Currently only a single output window will ever be created. Subsequent calls to the function will not create additional windows right now (but will raise / refresh the output window
+ at param url currently ignored! */
void openOutputWindow (const KURL &url=KURL ());
+/** @returns true if there is a known editor for this type of object, false otherwise */
bool canEditObject (RObject *object);
+/** Creates a new editor of an appropriate type, and loads the given object into the editor
+ at param object object to edit
+ at param initialize_to_empty Create an empty object (no data). Use with care!
+ at returns a pointer to the editor */
RKEditor *editObject (RObject *object, bool initialize_to_empty=false);
/** tell all DataEditorWindow s to syncronize changes to the R backend
// TODO: add RCommandChain parameter */
void flushAllData ();
+/** Close the active (attached) window. Safe to call even if there is no current active window (no effect in that case) */
void closeActiveWindow ();
+/** Close the given window, whether it is attached or detached.
+ at param window window to close */
void closeWindow (RKMDIWindow *window);
/** Closes all windows of the given type(s). Default call (no arguments) closes all windows
@param type: A bitwise OR of RKWorkplaceObjectType
@param state: A bitwise OR of RKWorkplaceObjectState */
void closeAll (int type=RKMDIWindow::AnyType, int state=RKMDIWindow::AnyState);
+/** Write a description of all current windows to the R backend. This can later be read by restoreWorkplace ()
+ at param chain command chain to place the command in */
void saveWorkplace (RCommandChain *chain=0);
+/** Load a description of windows from the R backend (created by saveWorkplace ()), and (try to) restore all windows accordingly
+ at param chain command chain to place the command in */
void restoreWorkplace (RCommandChain *chain=0);
+/** Clear the description as set by saveWorkplace () from the R backend. Simply removes the internal object. Since the description is only needed while the workplace is being saved / restored, this should be called shortly after saveWorkplace () and restoreWorkplace ()
+ at param cahin command chain to place the command in */
void clearWorkplaceDescription (RCommandChain *chain=0);
+/** In the current design there is only ever one workplace. Use this static function to reference it.
+ at returns a pointer to the workplace */
static RKWorkplace *mainWorkplace () { return main_workplace; };
signals:
- void lastWindowClosed (); // TODO: unused so far
+/** TODO: For future expansion. This signal is neither emitted nor used so far. It could be used to deactivate some options in the "Window" menu. Or maybe it can be removed? */
+ void lastWindowClosed ();
public slots:
+/** When windows are attached to the workplace, their QObject::destroyed () signal is connected to this slot. Thereby deleted objects are removed from the workplace automatically */
void windowDestroyed (QObject *window);
protected:
+/** handles the result of the command issued in restoreWorkplace. */
void rCommandDone (RCommand *command);
private:
+/** current list of windows. @See getObjectList () */
RKWorkplaceObjectList windows;
+/** the view. @See view () */
RKWorkplaceView *wview;
+/** Internal function to add an existing window to the list of mdi windows */
void addWindow (RKMDIWindow *window);
+/** static pointer to the workplace. @See mainWorkplace () */
static RKWorkplace *main_workplace;
};
Modified: trunk/rkward/rkward/windows/rkworkplaceview.h
===================================================================
--- trunk/rkward/rkward/windows/rkworkplaceview.h 2006-09-27 14:06:38 UTC (rev 768)
+++ trunk/rkward/rkward/windows/rkworkplaceview.h 2006-09-27 15:28:11 UTC (rev 769)
@@ -29,27 +29,44 @@
class RKWorkplaceView : public QWidget {
Q_OBJECT
public:
+/** constructor
+ at param parent parent QWidget */
RKWorkplaceView (QWidget *parent);
~RKWorkplaceView ();
+/** add the given window to the view */
void addPage (RKMDIWindow *widget);
+/** remove the given window to the view
+ at param destroyed if the window is already destroyed, set this to true */
void removePage (RKMDIWindow *widget, bool destroyed=false);
+/** activate the given window */
void setActivePage (RKMDIWindow *widget);
+/** @returns the currently active window */
RKMDIWindow *activePage ();
+/** Like activePage ()->shortCaption, but safe even if there is no active window
+ at returns the caption of the currently active window. */
QString activeCaption ();
+/** reimplemented form QWidget::setCaption () to emit captionChanged () when the caption changes */
void setCaption (const QString &caption);
signals:
+/** a new page / window was activated
+ at param widget the newly activated window */
void pageChanged (RKMDIWindow *widget);
+/** caption has changed
+ at param new_caption the new caption */
void captionChanged (const QString &new_caption);
public slots:
+/** like setActivePage (), but activates by internal id. Used internally */
void setPage (int page);
+/** called when the caption of a window changes. Updates the tab-label, and - if appropriate - the caption of this widget */
void childCaptionChanged (RKMDIWindow *widget);
private:
QTabBar *tabs;
QWidgetStack *widgets;
typedef QMap<int, RKMDIWindow*> PageMap;
PageMap pages;
+/** internal convenience function to get the internal id of the given window */
int idOfWidget (RKMDIWindow *widget);
};
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the rkward-tracker
mailing list