sbIPlaylistsource Interface Reference

The internal RDF Data Source that sends playlist data to the UI. More...

List of all members.

Public Member Functions

void feedPlaylist (in AString aRefName, in AString aContextGUID, in AString aTableName)
 Prepare a database table to be made available to the UI as an RDFDataSource.
void clearPlaylist (in AString aRefName)
 [DEPRECATED]
PRInt32 executeFeed (in AString aRefName)
 Prepare and execute the SQL queries required for a datasource to make the playlist available to the UI.
void setFilter (in AString aRefName, in PRInt32 aIndex, in AString aFilterString, in AString aFilterRefName, in AString aFilterColumn)
 Set a filter to act upon a datasource.
PRInt32 getNumFilters (in AString aRefName)
 Return the count of filters on a datasource.
void clearFilter (in AString aRefName, in PRInt32 aIndex)
 Remove a filter from a datasource.
AString getFilter (in AString aRefName, in PRInt32 aIndex)
 Get the filter string from a datasource's filter.
AString getFilterRef (in AString aRefName, in PRInt32 aIndex)
 Get the ref for the filter's published RDF datasource.
void setSearchString (in AString aRefName, in AString aSearchString)
 Set the search string on a datasource.
AString getSearchString (in AString aRefName)
 Get the search string on a datasource.
void setOrder (in AString aRefName, in AString aColumnName)
 Set the sort order on a datasource.
AString getOrder (in AString aRefName)
 Get the sort order from a datasource.
AString getRefGUID (in AString aRefName)
 Get the database guid string on a datasource.
AString getRefTable (in AString aRefName)
 Get the database table string on a datasource.
PRInt32 getRefRowCount (in AString aRefName)
 Get the row count on a datasource.
PRInt32 getRefColumnCount (in AString aRefName)
 Get the column count on a datasource.
AString getRefRowCellByColumn (in AString aRefName, in PRInt32 aRow, in AString aColumn)
 Get the value of a cell on a datasource.
PRInt32 getRefRowByColumnValue (in AString aRefName, in AString aColumn, in AString aValue)
 Calculate the row index of a cell based upon the value of a column.
PRBool isQueryExecuting (in AString aRefName)
 Determine if a datasource is currently executing its internal queries.
PRInt32 waitForQueryCompletion (in AString aRefName)
 Wait the main thread until the ref is completely updated.
void forceGetTargets (in AString aRefName, in PRBool isPermanent)
 Force the nsIRDFDataSource::GetTargets() method to be called.
void incomingObserver (in AString aRefName, in nsIDOMNode aObject)
 Hint to the interface that an observer is about to be attached.
void registerPlaylistCommands (in AString aContextGUID, in AString aTableName, in AString aPlaylistType, in sbIPlaylistCommands aCommandObj)
 Register sbIPlaylistCommands objects to be shown for specific playlists.
sbIPlaylistCommands getPlaylistCommands (in AString aContextGUID, in AString aTableName, in AString aPlaylistType)
 Retrieve the sbIPlaylistCommands object to be shown for a specific playlist.


Detailed Description

The internal RDF Data Source that sends playlist data to the UI.

sbIPlaylistsource acts as the intermediary between the database table that represents a library or a playlist and the display of that info into a <playlist> UI element.

When a playlist element is told to bind to a specific database table, the playlist asks sbIPlaylistsource to create a new RDF ref that can properly feed data to its internal xul tree (see: feedPlaylist(), executeFeed()). A table may be fed and made available to this interface without involving a playlist element by calling forceGetTargets() for that RefName.

The RefName param passed to feedPlaylist() is used from then on to identify each specific source for further modification or information. If you would like to obtain specific information about the data currently displayed in a playlist object, use that object's .ref property as the RefName parameter to these methods.

sbIPlaylistsource provides methods to implement various modifications to the underlying SQL queries that drive the display of a playlist table. Filters may be specified that feed a dependent RDF source and are used by the <filterlist> UI element when displaying a standard libaray (see: setFilter(), getNumFilters(), clearFilter(), getFilter(), getFilterRef()) and an override string may be specified to support a direct search feature (see: setSearchString(), getSearchString()).

This interface also allows direct access to the underlying data returned by the database, avoiding additional queries (see: getRefRowCount(), getRefColumnCount(), getRefRowCellByColumn(), getRefRowByColumnValue()) and can also return the table and guid of the query (see: getRefGUID(), getRefTable()).

Lastly, it acts as a centralized storehouse for sbIPlaylistCommands implementations. Registering a custom commands object into this interface will specify rules to be used to determine if those commands should be shown in any specific playlist element's display (see: registerPlaylistCommands(), getPlaylistCommands()).

See also:
playlist.xml

Definition at line 236 of file sbIPlaylistsource.idl.


Member Function Documentation

void sbIPlaylistsource::clearFilter ( in AString  aRefName,
in PRInt32  aIndex 
)

Remove a filter from a datasource.

This value can only be used for enumeration if setFilter() was properly called with its indices in order from 0

Parameters:
aRefName The unique identifier for the datasource
aIndex The index value of the filter to be referenced

void sbIPlaylistsource::clearPlaylist ( in AString  aRefName  ) 

[DEPRECATED]

Parameters:
aRefName The unique identifier for the datasource

PRInt32 sbIPlaylistsource::executeFeed ( in AString  aRefName  ) 

Prepare and execute the SQL queries required for a datasource to make the playlist available to the UI.

After calling feedPlaylist() and optionally calling setFilter(), call this method to launch the SQL queries and present the data to whomever is observing the feed.

Parameters:
aRefName The unique identifier for the datasource

void sbIPlaylistsource::feedPlaylist ( in AString  aRefName,
in AString  aContextGUID,
in AString  aTableName 
)

Prepare a database table to be made available to the UI as an RDFDataSource.

This method is called with the guid and table of a playlist and a string to be used as the ref="XXXXXX" param for the tree. The string must begin with "NC:" (don't look at me, that's what moz demands).

The string passed to this method will then be used as a reference to the underlying data source in all the other methods on this interface.

The datasource is not actually published until executeFeed() is called. This allows the coder to setup filters with setFilter() first.

Parameters:
aRefName The unique identifier for the datasource
aContextGUID The database identifier string
aTableName The playlist table name

void sbIPlaylistsource::forceGetTargets ( in AString  aRefName,
in PRBool  isPermanent 
)

Force the nsIRDFDataSource::GetTargets() method to be called.

At times, it may be convenient to feed a playlist, without actually displaying the playlist (for instance, sbIPlaylistPlayback operates upon datasources).

This method forces the internal RDF method called by the consumers of its data in RDF format, and properly constructs the internal structures necessary to properly query this interface for its information.

Todo:
I'm pretty sure this is broken right now
Parameters:
aRefName The unique identifier for the datasource
isPermanent If True, preserve the forceGetTargets state.

AString sbIPlaylistsource::getFilter ( in AString  aRefName,
in PRInt32  aIndex 
)

Get the filter string from a datasource's filter.

Parameters:
aRefName The unique identifier for the datasource
aIndex The index value of the filter to be referenced
Returns:
The filter string

AString sbIPlaylistsource::getFilterRef ( in AString  aRefName,
in PRInt32  aIndex 
)

Get the ref for the filter's published RDF datasource.

Parameters:
aRefName The unique identifier for the datasource
aIndex The index value of the filter to be referenced
Returns:
The filter's ref string

PRInt32 sbIPlaylistsource::getNumFilters ( in AString  aRefName  ) 

Return the count of filters on a datasource.

This value can only be used for enumeration if setFilter() was properly called with its indices in order from 0

Parameters:
aRefName The unique identifier for the datasource

AString sbIPlaylistsource::getOrder ( in AString  aRefName  ) 

Get the sort order from a datasource.

Parameters:
aRefName The unique identifier for the datasource
Returns:
The column on which sorting is being performed

sbIPlaylistCommands sbIPlaylistsource::getPlaylistCommands ( in AString  aContextGUID,
in AString  aTableName,
in AString  aPlaylistType 
)

Retrieve the sbIPlaylistCommands object to be shown for a specific playlist.

Given the guid, table, and type strings, return a duplicate instance of the sbIPlaylistCommands object registered.

The "type" string has precedence over the "guid"/"table" pair.

This method is only called by the playlist UI object, in playlist.xml

Todo:
Currently, new registrations overwrite previous registrations. BAD. Make them save and return an array. Please don't overwrite our standard commands.
Parameters:
aContextGUID The guid string for the playlist
aTableName The name of the playlist
aPlaylistType The type of the playlist
Returns:
A newly duplicated command object instance to be used for this playlist
See also:
sbIPlaylistCommands, playlist.xml

PRInt32 sbIPlaylistsource::getRefColumnCount ( in AString  aRefName  ) 

Get the column count on a datasource.

Parameters:
aRefName The unique identifier for the datasource
Returns:
The column count

AString sbIPlaylistsource::getRefGUID ( in AString  aRefName  ) 

Get the database guid string on a datasource.

Parameters:
aRefName The unique identifier for the datasource
Returns:
The guid string

PRInt32 sbIPlaylistsource::getRefRowByColumnValue ( in AString  aRefName,
in AString  aColumn,
in AString  aValue 
)

Calculate the row index of a cell based upon the value of a column.

Parameters:
aRefName The unique identifier for the datasource
aColumn The column name of the cell
aValue The value to test against
Returns:
The row index, or -1

AString sbIPlaylistsource::getRefRowCellByColumn ( in AString  aRefName,
in PRInt32  aRow,
in AString  aColumn 
)

Get the value of a cell on a datasource.

Parameters:
aRefName The unique identifier for the datasource
aRow The row index of the cell
aColumn The column name of the cell
Returns:
The cell value

PRInt32 sbIPlaylistsource::getRefRowCount ( in AString  aRefName  ) 

Get the row count on a datasource.

Parameters:
aRefName The unique identifier for the datasource
Returns:
The row count

AString sbIPlaylistsource::getRefTable ( in AString  aRefName  ) 

Get the database table string on a datasource.

Parameters:
aRefName The unique identifier for the datasource
Returns:
The table string

AString sbIPlaylistsource::getSearchString ( in AString  aRefName  ) 

Get the search string on a datasource.

Parameters:
aRefName The unique identifier for the datasource
Returns:
The search string

void sbIPlaylistsource::incomingObserver ( in AString  aRefName,
in nsIDOMNode  aObject 
)

Hint to the interface that an observer is about to be attached.

Because the nsIRDFObserver interface does not include information about the observing object, this method may be called before setting the datasources and ref attributes on a xul element to scope updates to the element's observer to a particular RefName string.

If code does not call this method, the accepted observer will be told to update for all changes to all refs published by this object. That's probably ugly and definitely a performance drain.

Parameters:
aRefName The unique identifier for the datasource
aObject The object acting as the observer

PRBool sbIPlaylistsource::isQueryExecuting ( in AString  aRefName  ) 

Determine if a datasource is currently executing its internal queries.

Parameters:
aRefName The unique identifier for the datasource
Returns:
True, if the query is executing

void sbIPlaylistsource::registerPlaylistCommands ( in AString  aContextGUID,
in AString  aTableName,
in AString  aPlaylistType,
in sbIPlaylistCommands  aCommandObj 
)

Register sbIPlaylistCommands objects to be shown for specific playlists.

The sbIPlaylistCommands interface is used to algorithmically define a set of commands to be rendered arbitrarily by a playlist ui object (currently, playlist.xml).

Commands can be registered for an entire database (by setting ContextGUID and leaving TableName null), or for any "type" characteristic.

Todo:
Currently, new registrations overwrite previous registrations. BAD. Make them save and return an array. Please don't overwrite our standard commands.
Parameters:
aContextGUID The guid string for the database to register against
aTableName The name of the table to register against
aPlaylistType The arbitrary type string to register against
aCommandObj The command object instance to be used for these playlists
See also:
sbIPlaylistCommands, playlist.xml

void sbIPlaylistsource::setFilter ( in AString  aRefName,
in PRInt32  aIndex,
in AString  aFilterString,
in AString  aFilterRefName,
in AString  aFilterColumn 
)

Set a filter to act upon a datasource.

This method is used to set or modify a filter on the datasource output.

A datasource may have a number of hierarchical column filters applied to it. These feed the filterlist elements in a library display.

Each filter creates its own datasource to feed a filterlist element, with its own unique FilterRefName (usually just the playlist RefName plus the FilterColumn string). It also must begin with "NC:" or it won't work.

The Index parameter specifies the hierarchy of the filters. Filters with lower indices will act upon the output of ones with higher indices. While any int values may be passed as indices, the getFilter() function must be called with that value to retrieve the filter. If they are not contiguous values, you cannot iterate them using getNumFilters().

The FilterString parameter is a semicolon delimited list of values that are matched via OR to the playlist itself. A blank string is analogous to the "All" selection in the filterlist element.

Parameters:
aRefName The unique identifier for the datasource
aIndex The hierarchical level of the filter to be set
aFilterString A semicolon list of values to filter against
aFilterRefName The unique identifier for the filter datasource
aFilterColumn The column name to filter against

void sbIPlaylistsource::setOrder ( in AString  aRefName,
in AString  aColumnName 
)

Set the sort order on a datasource.

The sort order should be the name of an existing column. The results will be sorted using that column data

Pass a blank string to reset to a default order.

Parameters:
aRefName The unique identifier for the datasource
aSearchString The column name on which to perform sorting

void sbIPlaylistsource::setSearchString ( in AString  aRefName,
in AString  aSearchString 
)

Set the search string on a datasource.

The syntax of the string should be a space-delimited list search terms. The results will only be items that match all the terms in displayed columns.

Pass a blank string to clear this value.

Parameters:
aRefName The unique identifier for the datasource
aSearchString The string defining the search

PRInt32 sbIPlaylistsource::waitForQueryCompletion ( in AString  aRefName  ) 

Wait the main thread until the ref is completely updated.

Parameters:
aRefName The unique identifier for the datasource
Returns:
The last error of the query


The documentation for this interface was generated from the following file:
Generated on Mon Aug 21 21:01:56 2006 for Songbird by  doxygen 1.4.7