diff --git a/doc/python/epydoc.css b/doc/python/epydoc.css index a1f99c8b1..2efb45ea0 100644 --- a/doc/python/epydoc.css +++ b/doc/python/epydoc.css @@ -78,7 +78,8 @@ td.footer { font-size: 85%; } * - Summary tables that contain user-defined groups mark those * groups using 'group header' rows. */ -td.table-header { font-weight: bold; +td.table-header, +th.group-header { font-weight: bold; text-align: left; padding: 6px 12px; border: 1px solid #BBB; @@ -86,10 +87,6 @@ td.table-header { font-weight: bold; td.table-header table { color: #000000; } td.table-header table a:link { color: #0000ff; } td.table-header table a:visited { color: #204080; } -th.group-header { background: #c0e0f8; color: #000000; - text-align: left; font-style: italic; - font-size: 115%; - border: 1px solid #608090; } /* Summary Tables (functions, variables, etc) * - Each object is described by a single row of the table with diff --git a/src/scripting/python/iconloader.sip b/src/scripting/python/iconloader.sip index c1cd94bb2..944d0c999 100644 --- a/src/scripting/python/iconloader.sip +++ b/src/scripting/python/iconloader.sip @@ -8,10 +8,10 @@ class IconLoader { Singleton class that loads icons from the system theme if possible, falling back on Clementine's builtin icons otherwise. -You can access the IconLoader directly, there is no need to create an instance -of the class first. +You can access the IconLoader methods directly, there is no need to create an +instance of the class first. - >>> clementine.IconLoader.Load("media-pause") + >>> clementine.IconLoader.Load("media-pause") Icons are identified by their name without any extension, and they follow the U{Freedesktop icon naming specification}. diff --git a/src/scripting/python/pythonengine.sip b/src/scripting/python/pythonengine.sip index d01affb75..079ddfe17 100644 --- a/src/scripting/python/pythonengine.sip +++ b/src/scripting/python/pythonengine.sip @@ -4,8 +4,38 @@ class PythonEngine { #include "scripting/python/pythonengine.h" %End +%Docstring +Helper functions for communicating with Clementine's Python interface. + +This is a singleton class, you can access its methods directly through the +C{clementine.pythonengine} object: + + >>> clementine.pythonengine.AddLogLine("Everything is ok") +%End + public: void AddLogLine(const QString& message, bool error = false); +%Docstring +AddLogLine(message, error=false) +Writes a line to the Clementine script console. + +Note that sys.stdout and sys.stderr are already redirected to the script +console, so you will not normally need to call this function. Instead you can +use C{print} directly:: + + # These lines are equivalent + print "Everything is ok" + clementine.pythonengine.AddLogLine("Everything is ok") + + # These lines are equivalent + print >>sys.stderr, "Everything is wrong" + clementine.pythonengine.AddLogLine("Everything is wrong", error=True) + +@param message: A line to write to the log. +@type message: str +@param error: If this is True then the message will appear in red. +@type error: bool +%End private: PythonEngine(); diff --git a/src/scripting/python/queue.sip b/src/scripting/python/queue.sip index 21d0c6d7f..8688cef60 100644 --- a/src/scripting/python/queue.sip +++ b/src/scripting/python/queue.sip @@ -4,22 +4,124 @@ struct Queue : QAbstractProxyModel { #include "playlist/queue.h" %End -public: - Queue(); +%Docstring +A model containing the list of songs that are enqueued on a playlist. +In Clementine each L{Playlist} has its own Queue object. The Queue keeps an +ordered list of items that are enqueued on that playlist. Whenever a song +finishes the top item is removed from the Queue and is played immediately. +When there are no items left on the Queue playback continues again in the normal +order. + +The L{Playlist} is a standard Qt item model where each row represents one item +in the playlist. The Queue is a Qt proxy model on top of the Playlist model, +which means that rows in the Queue can map directly onto rows in the Playlist. +Use C{mapToSource(index)} and C{mapFromSource(index)} to map rows in the Queue +to or from rows in the Playlist. + +You can't create Queue objects directly. Instead you have to get a Queue from +an existing playlist. + + >>> queue = clementine.playlists.current().queue() + >>> queue.Clear() +%End + +public: static const char* kRowsMimetype; - // Query the queue bool is_empty() const; - int PositionOf(const QModelIndex& source_index) const; - bool ContainsSourceRow(int source_row) const; - int PeekNext() const; +%Docstring +is_empty() -> bool +Checks whether the queue is empty. +%End + + int PositionOf(const QModelIndex& source_index) const; +%Docstring +PositionOf(source_index) -> int +Finds the position in the Queue of a playlist item. + +@param source_index: The index of an item in the underlying L{Playlist} model. +@type source_index: L{PyQt4.QtCore.QModelIndex} +@return: The position in the queue of the playlist item, or -1 if the playlist + item is invalid or is not in the queue. +%End + + bool ContainsSourceRow(int source_row) const; +%Docstring +ContainsSourceRow(source_row) -> bool +Checks whether a playlist row is in the queue. + +@param source_row: The row number of an item in the underlying L{Playlist} model. +@type source_row: int +%End + + int PeekNext() const; +%Docstring +PeekNext() -> int +Returns the row number in the L{Playlist} of the next item in the queue, leaving +the Queue unchanged. +%End - // Modify the queue int TakeNext(); +%Docstring +TakeNext() -> int +Like L{PeekNext()}, but removes the item from the Queue as well as returning it. +%End + void ToggleTracks(const QModelIndexList& source_indexes); +%Docstring +ToggleTracks(source_indexes) +Adds or removes the Playlist indexes to/from the queue. + +@param source_indexes: A list of indexes from the underlying L{Playlist} model. +@type source_indexes: list of L{PyQt4.QtCore.QModelIndex}es +%End + void Clear(); +%Docstring +Clear() +Removes all the items from the Queue. +%End + void Move(const QList& proxy_rows, int pos); +%Docstring +Move(proxy_rows, pos) +Moves a list of queued items to a different position in the queue. + +Example:: + + # Moves the second item to the front. + queue.Move([1], 0) + + # Moves the first three items to the end. + queue.Move([0, 1, 2], queue.rowCount() - 1) + +@param proxy_rows: A list of row numbers of items already in the queue. +@type proxy_rows: list of ints +@param pos: The new position in which to insert the items. +@type pos: int +%End + void MoveUp(int row); +%Docstring +MoveUp(row) +Moves the queued item up one position in the Queue. + +This is equivalent to:: + + queue.Move([row], row - 1) +%End + void MoveDown(int row); +%Docstring +MoveUp(row) +Moves the queued item down one position in the Queue. + +This is equivalent to:: + + queue.Move([row], row + 2) +%End + +private: + Queue(); }; diff --git a/src/scripting/python/taskmanager.sip b/src/scripting/python/taskmanager.sip index 3808d08d1..0359b2d8c 100644 --- a/src/scripting/python/taskmanager.sip +++ b/src/scripting/python/taskmanager.sip @@ -4,8 +4,35 @@ class TaskManager : QObject { #include "core/taskmanager.h" %End +%Docstring +API for managing progress notifications in Clementine's status bar. + +When you are performing a slow operation, such as downloading data from the +network or parsing a file, it is useful to be able to provide progress +information to the user. Clementine displays information about any running +tasks with a spinner animation in the status bar. + +When you start a new task, the TaskManager will give you an ID which you must +keep and use again later to update the task's progress or to mark it as +completed. + +This is a singleton class, you can access its methods directly through the +C{clementine.task_manager} object: + + >>> id = clementine.task_manager.StartTask("Finding some awesome music") + >>> clementine.task_manager.SetTaskProgress(id, 33, 100) + >>> clementine.task_manager.SetTaskProgress(id, 66, 100) + >>> clementine.task_manager.SetTaskFinished(id) + +@group Signals: TasksChanged, PauseLibraryWatchers, ResumeLibraryWatchers +%End + public: struct Task { +%Docstring +Object containing information about a running task. +%End + int id; QString name; int progress; @@ -14,17 +41,73 @@ public: }; QList GetTasks(); +%Docstring +GetTasks() -> list of L{Task}s +Returns a list of all the tasks that are currently running. + +Modifying the items in this list will have no effect - you have to use the other +methods in this class to update the status of a task. +%End int StartTask(const QString& name); +%Docstring +StartTask(name) -> int +Begins a new task. + +@param name: A descriptive name of the task that will be displayed in the + status bar. +@type name: str +@return: A new ID for this task. Use this ID when calling L{SetTaskFinished} + later. +@note: Do not include ellipsis (...) in the name of the task, this is added + for you by the status bar. +%End + void SetTaskBlocksLibraryScans(int id); +%Docstring +SetTaskBlocksLibraryScans(id) +Forces any library scans to wait until this task is complete. + +It may be useful to set this flag on a task that modifies files in the library. +The LibraryWatcher will wait until the task is complete before starting to +rescan the Library. +%End + void SetTaskProgress(int id, int progress, int max = 0); +%Docstring +SetTaskProgress(id, progress, max=0) +Updates the progress for this task. + +The status bar shows the percentage progress of this task, calculated by +C{(progress / max * 100)}. C{max} must be provided the first time this +method is called for a given task, but after that it can be omitted to keep the +old value. +%End + void SetTaskFinished(int id); +%Docstring +SetTaskFinished(id) +Marks the given task as finished, removing it from the status bar. +%End signals: void TasksChanged(); +%Docstring +TasksChanged() +Emitted when the list of tasks returned by L{GetTasks()} is changed. +%End void PauseLibraryWatchers(); +%Docstring +PauseLibraryWatchers() +Emitted when L{SetTaskBlocksLibraryScans()} is called on a task. +%End + void ResumeLibraryWatchers(); +%Docstring +ResumeLibraryWatchers() +Emitted when all tasks that blocked library scans have finished. +%End private: TaskManager();