i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Checkin for Gabe Yoder

Browse Source 
git-svn-id: file:///srv/svn/repos/haiku/trunk/current@1590 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
DarkWyrm
2002-10-22 00:08:45 +00:00
parent 809cd10db5
commit b010ca6720
9 changed files with 746 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/develop/app/usecases/BClipboardUseCases.html
+153
View File
@@ -0,0 +1,153 @@
<HTML>
<HEAD>
<TITLE>BClipboard Use Cases and Implementation Details</TITLE>
</HEAD>
<BODY BGCOLOR="white" LINK="#000067" VLINK="#000067" ALINK="#0000FF">
<FONT FACE="Verdana,Arial,Helvetica,sans-serif" SIZE="-1">
<H1>BClipboard Use Cases and Implementation Details:</H1>
<P>This document describes the BClipboard interface and some basics of how it is implemented.
The document has the following sections:</P>
<OL>
<LI><A HREF="#interface">BClipboard Interface</A></LI>
<LI><A HREF="#usecases">BClipboard Use Cases</A></LI>
<LI><A HREF="#implement">BClipboard Implementation</A></LI>
</OL>
<A NAME="interface"></A><H2>BClipboard Interface:</H2>
<P>The BClipboard class provides an interface to a named, system-wide, temporary storage resource.
Access to the system clipboard is provided by the be_clipboard variable provided by a BApplication object (or by constructing a clipboard with the name "system").
The best source of information for the BClipboard interface can be found
<A HREF="file:///boot/beos/documentation/Be%20Book/The%20Application%20Kit/Clipboard.html">here in the Be Book</A>.
</P>
<A NAME="usecases"></A><H2>BClipboard Use Cases:</H2>
<P>The following use cases cover the BClipboard functionality:</P>
<OL>
<LI><P><B>Construction:</B> A BClipboard will accept one or two arguments to construction.
A name is required for identifying the clipboard. The discard argument indicates whether the
clipboard data should be discarded between boots. Te discard argument defaults to false, however
this is meaningless since functionality has not been implemented to maintain clipboard data
between boots.
After construction, the queue is empty.</P></LI>
<LI><P><B>Destruction:</B> The destructor destroys the BClipboard object, however the system-wide clipboard itself is unaffected.</P></LI>
<LI><P><B>Writing to clipboard 1:</B>
The normal procedure for writing data consists of the following: locking the clipboard via Lock(), clearing the
data via Clear(), adding data to the clipboard message, committing the data via Commit(), and unlocking the
clipboard via Unlock().
</P></LI>
<LI><P><B>Writing to clipboard 2:</B>
The data which is to be written is not added directly to the BClipboard object, but is added to the data
message for the BClipboard. The message is obtained by calling BClipboard::Data(). Data is added in fields
of type B_MIME_TYPE. The name of the field corresponds to the MIME type of the data. If multiple fields are
added, they should contain the same data, but formatted for different MIME types.
</P></LI>
<LI><P><B>Writing to clipboard 3:</B>
In the event that one wishes to back out of writing process before calling Commit(), Revert() must be called.
Otherwise, the changes to the clipboard remain in the BClipboard object.
</P></LI>
<LI><P><B>Reading from clipboard 1:</B>
The normal procedure for reading data consists of the following: locking the clipboard via Lock(), obtaining
the data from the clipboards data message, and unlocking the clipboard via Unlock().
</P></LI>
<LI><P><B>Reading from clipboard 2:</B>
The data message is obtained from a call to BClipboard::Data(). Data is obtained from the message by using
BMessage::FindData for a specified MIME type.
</P></LI>
<LI><P><B>Reading from clipboard 3:</B>
The data is uploaded from the system when Lock() is called, therefore any data which is written to the clipboard
between the calls to Lock() and Data() will not be included in the data message.
</P></LI>
<LI><P><B>Reading from clipboard 4:</B>
It is permissible to Unlock() the clipboard before calling FindData on the data message.
</P></LI>
<LI><P><B>Clearing:</B>
The Clear() function is used to remove all data from the clipboard and is used before adding new data which is
to be written to the clipboard. Clear() returns B_ERROR if the BClipboard is not locked, and returns B_OK if
it is locked.
</P></LI>
<LI><P><B>Committing:</B>
The Commit() function is used to upload data from the BClipboard to the system. The data is immediately
available to other applications once Commit() has been called. Commit() returns B_ERROR if the BClipboard
is not locked, and returns B_OK if it is locked.
</P></LI>
<LI><P><B>Revert:</B>
The Revert() function is used to synchronize the data in the BClipboard to the system. This is only needed in
case one begins to modify the data message and wishes to back out of the changes. Revert() returns B_ERROR if
the BClipboard is not locked, and returns B_OK if it is locked.
</P></LI>
<LI><P><B>Accessing data:</B>
Data() is used to obtain a pointer to the BClipboard's data message. One is expected to read and write data
directly to the message, but the message must not be freed or dispatched. Data() returns NULL if the
BClipboard is not locked.
</P></LI>
<LI><P><B>Accessing a data source:</B>
DataSource() is used to obtain a BMessenger pointed at the BApplication which last committed data to the
clipboard. There is no requirement for the the BClipboard to be locked when calling DataSource().
</P></LI>
<LI><P><B>Obtaining a count:</B>
The count refers to the number of times that data has been uploaded to the clipboard.
There are two count functions. SystemCount() returns an up to date count which is obtained from the system.
Count() returns a cached count. The cached count is set to zero upon creation
of the BClipboard, and is updated when Lock() or Commit() is called.
</P></LI>
<LI><P><B>Locking:</B>
Lock() is used to upload data from the system into the BClipboard object and prevent other threads in the
application from using it. It must be called before reading or writing data to the BClipboard. It blocks
if the BClipboard is already locked. The return value is true if the BClipboard is successfully locked, or
false if the BClipboard was deleted while Lock() was blocked.
</P></LI>
<LI><P><B>Unlocking:</B>
Unlock() is used to unlock the BClipboard and allow other threads in the application to use it.
</P></LI>
<LI><P><B>Checking lock status:</B>
IsLocked() returns true if the BClipboard is locked, and false if it is not locked.
</P></LI>
<LI><P><B>Checking clipboard name:</B>
Name() returns a string containing the name of the clipboard. It is not necessary for the BClipboard to be
locked when calling Name().
</P></LI>
<LI><P><B>Watching a clipboard:</B>
StartWatching and StopWatching are used to enable and disable watching of a clipboard. When the clipboard is
changed, a B_CLIPBOARD_CHANGED message is sent to the target specified in the call to StartWatching.
</P></LI>
</OL>
<A NAME="implement"></A><H2>BClipboard Implementation:</H2>
<P>
The BClipboard class is implemented via a message passing system between the BClipboard, the Roster, and
the Clipboard Handler associated with the Roster. Details of the message passing protocol are listed in the
Roster documentation.
</P>
</BODY>
</HTML>
docs/develop/app/usecases/BCursorUseCases.html
+50
View File
@@ -0,0 +1,50 @@
<HTML>
<HEAD>
<TITLE>BCursor Use Cases and Implementation Details</TITLE>
</HEAD>
<BODY BGCOLOR="white" LINK="#000067" VLINK="#000067" ALINK="#0000FF">
<FONT FACE="Verdana,Arial,Helvetica,sans-serif" SIZE="-1">
<H1>BCursor Use Cases and Implementation Details:</H1>
<P>This document describes the BCursor interface and some basics of how it is implemented.
The document has the following sections:</P>
<OL>
<LI><A HREF="#interface">BCursor Interface</A></LI>
<LI><A HREF="#usecases">BCursor Use Cases</A></LI>
<LI><A HREF="#implement">BCursor Implementation</A></LI>
</OL>
<A NAME="interface"></A><H2>BCursor Interface:</H2>
<P>The BCursor class is a simple class used to represent a mouse cursor as an object instead of an array of pixel data. The best source of information for the BCursor interface can be found
<A HREF="file:///boot/beos/documentation/Be%20Book/The%20Application%20Kit/Cursor.html">here in the Be Book</A>.
</P>
<A NAME="usecases"></A><H2>BCursor Use Cases:</H2>
<P>The following use cases cover the BCursor functionality:</P>
<OL>
<LI><P><B>Construction 1:</B> The first BCursor constructor requires a pointer to the pixel data. The format for the pixel data is described
<A HREF="file:///boot/beos/documentation/Be%20Book/The%20Application%20Kit/Cursor.html#Cursor_Data_Format">here in the Be Book</A>.
This pixel data is used to initialize the BCursor, but BCursor does not take ownership of the data, therefore you are responsible for freeing the memory after construction.</P></LI>
<LI><P><B>Construction 2:</B> The second BCursor constructor requires a BMessage as an archive, however BCursor does not currently support archiving. Do not use this constructor.</P></LI>
<LI><P><B>Destruction:</B> This releases all resources used by the BCursor.</P></LI>
<LI><P><B>Instantiate:</B> This always returns NULL since it relies on the second constructor (which is not currently supported). If it were implemented, this would return a new BArchivable consisting of a BCursor created from the archive passed in as an argument. </P></LI>
</OL>
<A NAME="implement"></A><H2>BCursor Implementation:</H2>
<P>All meaningful work of the BCursor is implemented in the first constructor. The constructor establishes a link with the app_server and sends it the pixel data. The app_server provides the BCursor with a token which identifies the pixel data. When BApplication::SetCursor(BCursor) is called, it must get the needed cursor data by obtaining the BCursor's token (BApplication is a friend of BCursor) and using the token to request the data from the app_server. Note that BCursor does not internally store the pixel data.</P>
</BODY>
</HTML>
headers/private/app/RegistrarDefs.h
+8
View File
@@ -81,6 +81,13 @@ enum {
B_REG_GET_MESSAGE_RUNNER_INFO = 'rgri',
// internal registrar messages
B_REG_ROSTER_SANITY_EVENT = 'rgir',
// clipboard handler requests
B_REG_ADD_CLIPBOARD = 'rgca',
B_REG_GET_CLIPBOARD_COUNT = 'rgcc',
B_REG_CLIPBOARD_START_WATCHING = 'rgcw',
B_REG_CLIPBOARD_STOP_WATCHING = 'rgcx',
B_REG_DOWNLOAD_CLIPBOARD = 'rgcd',
B_REG_UPLOAD_CLIPBOARD = 'rgcu',
};
// B_REG_MIME_SET_PARAM "which" constants
@@ -127,3 +134,4 @@ struct flat_app_info {
};
#endif // REGISTRAR_DEFS_H
src/kits/app/Clipboard.cpp
+88 -7
View File
@@ -28,9 +28,12 @@
// Standard Includes -----------------------------------------------------------
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
// System Includes -------------------------------------------------------------
#include <Clipboard.h>
#include <RegistrarDefs.h>
#include <Application.h>
// Project Includes ------------------------------------------------------------
@@ -44,14 +47,26 @@
//------------------------------------------------------------------------------
BClipboard::BClipboard(const char *name, bool transient = false)
{
/* Not complete yet */
fName = strdup(name);
fData = new BMessage();
fCount = 0;
fSystemCount = 0;
BMessage message(B_REG_GET_CLIPBOARD_MESSENGER), reply;
if ( (_send_to_roster_(&message, &reply, false) == B_OK) &&
(reply.what == B_REG_SUCCESS) &&
(reply.FindMessenger("messenger",&fClipHandler) == B_OK) )
{
BMessage handlerMessage(B_REG_ADD_CLIPBOARD), handlerReply;
int32 result;
if ( (handlerMessage.AddString("name",fName) == B_OK) &&
(fClipHandler.SendMessage(&message, &reply) == B_OK) )
reply.FindInt32("result",&result);
}
}
//------------------------------------------------------------------------------
BClipboard::~BClipboard()
{
/* Not complete yet? */
free(fName);
delete fData;
}
@@ -63,30 +78,57 @@ const char* BClipboard::Name() const
//------------------------------------------------------------------------------
uint32 BClipboard::LocalCount() const
{
return fCount;
/* fSystemCount contains the total number of writes to the clipboard.
fCount contains the number of writes to the clipboard done by this
BClipboard.
*/
return fSystemCount;
}
//------------------------------------------------------------------------------
uint32 BClipboard::SystemCount() const
{
/* Need to upload count data from app server, and update fCount */
int32 val;
BMessage message(B_REG_GET_CLIPBOARD_COUNT), reply;
if ( (message.AddString("name",fName) == B_OK) &&
(fClipHandler.SendMessage(&message, &reply) == B_OK) &&
(reply.FindInt32("count",&val) == B_OK) )
return (uint32)val;
return fCount;
return 0;
}
//------------------------------------------------------------------------------
status_t BClipboard::StartWatching(BMessenger target)
{
BMessage message(B_REG_CLIPBOARD_START_WATCHING), reply;
if ( (message.AddString("name",fName) == B_OK) &&
(message.AddMessenger("target", target ) == B_OK) &&
(fClipHandler.SendMessage(&message, &reply) == B_OK) )
return B_OK;
return B_ERROR;
}
//------------------------------------------------------------------------------
status_t BClipboard::StopWatching(BMessenger target)
{
BMessage message(B_REG_CLIPBOARD_STOP_WATCHING), reply;
if ( (message.AddString("name",fName) == B_OK) &&
(message.AddMessenger("target", target ) == B_OK) &&
(fClipHandler.SendMessage(&message, &reply) == B_OK) )
return B_OK;
return B_ERROR;
}
//------------------------------------------------------------------------------
bool BClipboard::Lock()
{
/* Will this work correctly if clipboard is deleted while still waiting on
fLock.Lock() ? */
bool retVal;
retVal = fLock.Lock();
/* Still need to upload clipboard data to fData */
/* Involves something with DownloadFromSystem */
if ( retVal &&
(DownloadFromSystem() != B_OK) )
{
retVal = false;
fLock.Unlock();
}
return retVal;
}
@@ -103,18 +145,32 @@ bool BClipboard::IsLocked() const
//------------------------------------------------------------------------------
status_t BClipboard::Clear()
{
if ( AssertLocked() &&
(fData->MakeEmpty() == B_OK) )
return B_OK;
return B_ERROR;
}
//------------------------------------------------------------------------------
status_t BClipboard::Commit()
{
if ( AssertLocked() &&
(UploadToSystem() == B_OK) )
return B_OK;
return B_ERROR;
}
//------------------------------------------------------------------------------
status_t BClipboard::Revert()
{
if ( AssertLocked() &&
(fData->MakeEmpty() == B_OK) &&
(DownloadFromSystem() == B_OK) )
return B_OK;
return B_ERROR;
}
//------------------------------------------------------------------------------
BMessenger BClipboard::DataSource() const
{
return fDataSource;
}
//------------------------------------------------------------------------------
BMessage* BClipboard::Data() const
@@ -126,10 +182,12 @@ BMessage* BClipboard::Data() const
//------------------------------------------------------------------------------
BClipboard::BClipboard(const BClipboard &)
{
/* This is private, and I don't use it, so I'm not going to implement it */
}
//------------------------------------------------------------------------------
BClipboard & BClipboard::operator=(const BClipboard &)
{
/* This is private, and I don't use it, so I'm not going to implement it */
}
//------------------------------------------------------------------------------
void BClipboard::_ReservedClipboard1()
@@ -146,14 +204,37 @@ void BClipboard::_ReservedClipboard3()
//------------------------------------------------------------------------------
bool BClipboard::AssertLocked() const
{
/* How should this be different from IsLocked() */
return fLock.IsLocked();
}
//------------------------------------------------------------------------------
status_t BClipboard::DownloadFromSystem(bool force=false)
{
/* What does force mean? */
BMessage message(B_REG_DOWNLOAD_CLIPBOARD), reply;
if ( (message.AddString("name",fName) == B_OK) &&
(fClipHandler.SendMessage(&message, &reply) == B_OK) &&
(reply.FindMessage("data",fData) == B_OK) &&
(reply.FindMessenger("data source",&fDataSource) == B_OK) &&
(reply.FindInt32("count",(int32 *)(&fSystemCount)) == B_OK) )
return B_OK;
return B_ERROR;
}
//------------------------------------------------------------------------------
status_t BClipboard::UploadToSystem()
{
BMessage message(B_REG_UPLOAD_CLIPBOARD), reply;
if ( (message.AddString("name",fName) == B_OK) &&
(message.AddMessage("data",fData) == B_OK) &&
(message.AddMessenger("data source", be_app_messenger ) == B_OK) &&
(fClipHandler.SendMessage(&message, &reply) == B_OK) &&
(reply.FindInt32("count",(int32 *)(&fSystemCount)) == B_OK) )
{
fCount++;
return B_OK;
}
return B_ERROR;
}
//------------------------------------------------------------------------------
src/servers/registrar/ClipboardHandler.cpp
+133
View File
@@ -1,6 +1,7 @@
// ClipboardHandler.cpp
#include <Message.h>
#include <RegistrarDefs.h>
#include "ClipboardHandler.h"
@@ -32,10 +33,142 @@ ClipboardHandler::~ClipboardHandler()
void
ClipboardHandler::MessageReceived(BMessage *message)
{
BString name;
BMessage reply;
switch (message->what) {
B_REG_ADD_CLIPBOARD:
{
if ( message->FindString("name",&name) != B_OK )
{
reply.AddInt32("result",0);
}
else
{
fClipboardTree.AddNode(name);
reply.AddInt32("result",1);
}
reply.what = B_REG_RESULT;
message->SendReply(&reply);
}
break;
B_REG_GET_CLIPBOARD_COUNT:
{
if ( message->FindString("name",&name) != B_OK )
{
reply.AddInt32("result",0);
}
else
{
ClipboardTree *node = fClipboardTree.GetNode(name);
if ( node )
{
reply.AddInt32("count",(uint32)(node->GetCount()));
reply.AddInt32("result",1);
}
else
reply.AddInt32("result",0);
}
reply.what = B_REG_RESULT;
message->SendReply(&reply);
}
break;
B_REG_CLIPBOARD_START_WATCHING:
{
BMessenger target;
if ( (message->FindString("name",&name) != B_OK) ||
(message->FindMessenger("target",&target) != B_OK) )
{
reply.AddInt32("result",0);
}
else
{
ClipboardTree *node = fClipboardTree.GetNode(name);
if ( node && node->AddWatcher(&target) )
reply.AddInt32("result",1);
else
reply.AddInt32("result",0);
}
reply.what = B_REG_RESULT;
message->SendReply(&reply);
}
break;
B_REG_CLIPBOARD_STOP_WATCHING:
{
BMessenger target;
if ( (message->FindString("name",&name) != B_OK) ||
(message->FindMessenger("target",&target) != B_OK) )
{
reply.AddInt32("result",0);
}
else
{
ClipboardTree *node = fClipboardTree.GetNode(name);
if ( node && node->RemoveWatcher(&target) )
reply.AddInt32("result",1);
else
reply.AddInt32("result",0);
}
reply.what = B_REG_RESULT;
message->SendReply(&reply);
}
break;
B_REG_DOWNLOAD_CLIPBOARD:
{
if ( message->FindString("name",&name) != B_OK )
{
reply.AddInt32("result",0);
}
else
{
ClipboardTree *node = fClipboardTree.GetNode(name);
if ( node )
{
reply.AddMessage("data",node->GetData());
reply.AddMessenger("data source",*node->GetDataSource());
reply.AddInt32("count",(uint32)(node->GetCount()));
reply.AddInt32("result",1);
}
else
reply.AddInt32("result",0);
}
reply.what = B_REG_RESULT;
message->SendReply(&reply);
}
break;
B_REG_UPLOAD_CLIPBOARD:
{
BMessage data;
BMessenger dataSource;
ClipboardTree *node = NULL;
if ( (message->FindString("name",&name) != B_OK) ||
(message->FindMessage("data",&data) != B_OK) ||
(message->FindMessenger("data source",&dataSource) != B_OK) )
{
reply.AddInt32("result",0);
}
else
{
node = fClipboardTree.GetNode(name);
if ( node )
{
node->SetData(&data);
node->SetDataSource(&dataSource);
reply.AddInt32("count",(uint32)(node->IncrementCount()));
reply.AddInt32("result",1);
}
else
reply.AddInt32("result",0);
}
reply.what = B_REG_RESULT;
message->SendReply(&reply);
if ( node )
node->NotifyWatchers();
}
break;
default:
BHandler::MessageReceived(message);
break;
}
}
src/servers/registrar/ClipboardHandler.h
+5
View File
@@ -4,6 +4,8 @@
#define CLIPBOARD_HANDLER_H
#include <Handler.h>
#include <Message.h>
#include "ClipboardTree.h"
class ClipboardHandler : public BHandler {
public:
@@ -11,6 +13,9 @@ public:
virtual ~ClipboardHandler();
virtual void MessageReceived(BMessage *message);
private:
ClipboardTree fClipboardTree;
};
#endif // CLIPBOARD_HANDLER_H
src/servers/registrar/ClipboardTree.cpp
+119
View File
@@ -0,0 +1,119 @@
// ClipboardTree.cpp
#include <Message.h>
#include <Clipboard.h>
#include "ClipboardTree.h"
/*!
\class ClipboardTree
\brief Implements a tree containing clipboards and their data
*/
// constructor
/*! \brief Creates and initializes a ClipboardTree.
*/
ClipboardTree::ClipboardTree()
{
fName = "";
fCount = 0;
fLeftChild = NULL;
fRightChild = NULL;
}
// destructor
/*! \brief Frees all resources associate with this object.
*/
ClipboardTree::~ClipboardTree()
{
if ( fLeftChild )
delete fLeftChild;
if ( fRightChild )
delete fRightChild;
}
void ClipboardTree::AddNode(BString name)
{
if ( fName == "" )
{
fName = name;
return;
}
if ( fName == name )
return;
if ( name < fName )
{
if ( !fLeftChild )
fLeftChild = new ClipboardTree;
fLeftChild->AddNode(name);
return;
}
if ( !fRightChild )
fRightChild = new ClipboardTree;
fRightChild->AddNode(name);
}
ClipboardTree* ClipboardTree::GetNode(BString name)
{
if ( fName == "" )
return NULL;
if ( fName == name )
return this;
if ( name < fName )
{
if ( !fLeftChild )
return NULL;
return fLeftChild->GetNode(name);
}
if ( !fRightChild )
return NULL;
return fRightChild->GetNode(name);
}
uint32 ClipboardTree::GetCount()
{
return fCount;
}
uint32 ClipboardTree::IncrementCount()
{
fCount++;
return fCount;
}
BMessage* ClipboardTree::GetData()
{
return &fData;
}
void ClipboardTree::SetData(BMessage *data)
{
fData = *data;
}
BMessenger* ClipboardTree::GetDataSource()
{
return &fDataSource;
}
void ClipboardTree::SetDataSource(BMessenger *dataSource)
{
fDataSource = *dataSource;
}
bool ClipboardTree::AddWatcher(BMessenger *watcher)
{
return fWatchingService.AddWatcher(*watcher);
}
bool ClipboardTree::RemoveWatcher(BMessenger *watcher)
{
return fWatchingService.RemoveWatcher(*watcher,true);
}
void ClipboardTree::NotifyWatchers()
{
BMessage message(B_CLIPBOARD_CHANGED);
fWatchingService.NotifyWatchers(&message,NULL);
}
src/servers/registrar/ClipboardTree.h
+37
View File
@@ -0,0 +1,37 @@
// ClipboardTree.h
#ifndef CLIPBOARD_TREE_H
#define CLIPBOARD_TREE_H
#include <String.h>
#include <Message.h>
#include <Messenger.h>
#include "WatchingService.h"
class ClipboardTree {
public:
ClipboardTree();
~ClipboardTree();
void AddNode(BString name);
ClipboardTree* GetNode(BString name);
uint32 GetCount();
uint32 IncrementCount();
BMessage *GetData();
void SetData(BMessage *data);
BMessenger *GetDataSource();
void SetDataSource(BMessenger *dataSource);
bool AddWatcher(BMessenger *watcher);
bool RemoveWatcher(BMessenger *watcher);
void NotifyWatchers();
private:
BString fName;
BMessage fData;
BMessenger fDataSource;
ClipboardTree *fLeftChild;
ClipboardTree *fRightChild;
uint32 fCount;
WatchingService fWatchingService;
};
#endif // CLIPBOARD_TREE_H
src/servers/registrar/Jamfile
+1
View File
@@ -7,6 +7,7 @@ UsePrivateHeaders storage ;
Server obos_registrar :
AppInfoList.cpp
ClipboardHandler.cpp
ClipboardTree.cpp
Event.cpp
EventMaskWatcher.cpp
EventQueue.cpp