kr_group.h

这是法国Kaleido公司提供了一个手机mmi设计平台

/***************************************************************************
KR_Group.h  -  
-------------------
begin                : Tue Mar 3 2004
copyright            : (C) 2004 by DigitalAirways
email                : [e-mail]
***************************************************************************/

/*
* Copyright (c) 2000-2004 DigitalAirways, sarl. All Rights Reserved.
*
* This software is the confidential and proprietary information of
* DigitalAirways, sarl. ("Confidential Information").  You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with DigitalAirways.
* A copy of this license is included in the licence.txt file included
* in this software package.
*/

/*
**************************************************************
* TODO
**************************************************************

- 



**************************************************************
* HISTORY
**************************************************************

- 
*/

#ifndef __KR_GROUP__
#define __KR_GROUP__

#include "KR_Object.h"
#include "KR_Plugin.h"
#include "KR_JitMapper.h"
#include "KR_GroupPopulator.h"
#include "KR_KRuntime.h"
#include "KR_View.h"
#include "KR_Option.h"
#include "EB_PFWImage.h"

class  KREBDLIBS_API Group :  public Plugin {

	friend class View;
	friend class KPage;
	friend class Option;

private:
	/**
 Leaves dangling ptr if not folowed by a Layout()->clearSlots()
	*/
		void deleteLazyOption(long i);

protected:	

	char* fName;
	KPage* fPage;

	View* fView;
	long fViewId;

	boolean fRotate;
	boolean fAutoAccesskeys;

	char*	fGroupParam;

	Option* fOptionAccepted;
	Option* fActivatingOption;

	long fActivateStamp;
	boolean fPermanentActivate;

	char* fJitMapperClass;
	char* fJitMapperParam;
#ifdef DEV_CONSISTENCY
	char* fJitMapperVersion;
#endif

	char* fPopulatorClass;
	GroupPopulator* fPopulator;
	char* fPopulatorParam;
#ifdef DEV_CONSISTENCY
	char* fPopulatorVersion;
#endif

	char* fStoreKey;

	boolean fCacheRefreshPopulatorOptions;
	boolean fCacheRefreshPopulatorNbOptions;
	boolean fCacheDeletePopulatorOptions;

	unsigned long fStamp4Options;

	char* fBgSrcOn;
	char* fBgSrcOff;

	Group* fNextFocusGroup;
	long fNextFocusGroupId;
	boolean fNextFocusGroupActivate;
	Group* fPrevFocusGroup;
	long fPrevFocusGroupId;
	boolean fPrevFocusGroupActivate;
	long fFirstOptionToShow;

	SmallArrayList* /* Option* */ fOptions;
	SmallArrayList* /* Option* */ fTemplateOptions;

	boolean	fPersistentFocus;
	long fFocusIndex;
	long fInitialFocusIndex;

	long fTemplateOptionId;

	void initGroup();

	virtual void marshalRestore(ObjectReader* reader, long version, Group** previousGroup, View** previousView, Option** previousOption);
	void marshalRestoreCurrent(ObjectReader* reader, long version, Group** previousGroup, View** previousView, Option** previousOption);
	void marshalRestore30(ObjectReader* reader, long version);

	virtual void complete(Serializer* serializer) ;

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>postRestore</method>
	<java>public void postRestore(int version)</java>
	<cpp>void postRestore(long version)</cpp>
	<descr>
	<p>This method allows to do some initialization work (by overriding it). It is called once the whole page has been loaded.</p>
	<note>Be aware that the focus of a Group is NOT defined in the post restore phase (it will be in the activate phase). Group.getFocusIndex() returns -4 (undefined focus).</note>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	virtual void postRestoreInternal(long version);

	void allocateOptionsList(long min);

	long getAdjustedFocusIndex();

	boolean wasActivated() ;

	void adapt4Group(Option* o, long index) ;


public:	

	virtual	void init(char* /*param*/) {}
	DEFINE_NEW(Group);
	DEFINE_DELETE(Group);

	Group(GContext* newGContext, char* name): Plugin(newGContext) {
		ASSERT_MEMORY_OWNERSHIP(this, name);
		initGroup();
		setName(name);
	}

	Group(GContext* newGContext): Plugin(newGContext) {
		initGroup();
	}

	virtual ~Group() ;			

	virtual boolean isHandleAction(long actionid);

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>doAction</method>
	<cpp>virtual boolean doAction(long actionid, char* value)</cpp>
	<java>public boolean doAction(int actionid, String value) throws Throwable</java>
	<descr>
	<p>This is the actions method handler of the groups. Action IDs are defined in the EB_Defs.h and com.digitalairways.browser.Action.java.</p>
	</descr>
	<notes>
	<p>This method may be overriden in a Group plugin to provide special behaviors as navigating on a down action for example.</p>
	</notes>
	<examples></examples>
	</api>
</page>
</kaleidoc>
	*/
	virtual boolean doAction(long actionid, char* value);

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getName</method>
	<cpp>char* getName()</cpp>
	<descr>
	<p>Returns the name of the Group. The name is given in Kaleido Design when it is created.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getName() {
		return fName;
	}

	void setPage(KPage* p) {
		fPage=p;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getJitMapperParam</method>
	<java>public final String getJitMapperParam()</java>
	<cpp>char* getJitMapperParam()</cpp>
	<descr>
	<p>Returns the plug-in param for this group. This param is initially set as third argument in the plugin definition in one of the setup.bsh file.</p>
	<p>In the C version, the ownership of the returned string is not transferred to the caller.</p>

	<code>
	Setup.addJitmapper("Classroom Default",
	"com.digitalairways.kaleido.classroom.DefaultJitMapper", "The jitMapperParam");
	</code>
	<p>This param can be retrieved by calling getGroup().getJitMapperParam() from the JitMapper code.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getJitMapperParam() {
		return fJitMapperParam;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getPopulatorParam</method>
	<java>String getPopulatorParam()</java>
	<cpp>char* getPopulatorParam()</cpp>
	<descr>
	<p>Returns the plug-in param for this group. This param is initially set as third argument in the plugin definition in one of the setup.bsh file:</p>
	<p>In the C version, the ownership of the returned string is not transferred to the caller.</p>
	<code>
	Setup.addPopulator("PeopleList",
	"com.digitalairways.kaleido.classroom.PeopleListPopulator", "The populator param") ;
	</code>
	<p>This param can be retrieved by calling getGroup().getPopulatorParam() from the populator code.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getPopulatorParam() {
		return fPopulatorParam;
	}

	/*

	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getPage</method>
	<cpp>KPage* getPage()</cpp>
	<descr>
	<p>Returns the KPage the Group belongs to.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	KPage* getPage() {
		return fPage;
	}
	void setNextFocusGroup(Group* nextFocusGroup) {
		fNextFocusGroup = nextFocusGroup;
	}

	void setPrevFocusGroup(Group* prevFocusGroup) {
		fPrevFocusGroup = prevFocusGroup;
	}


	void setFirstOptionToShow(long index) {
		fFirstOptionToShow = index;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getFirstOptionToShow</method>
	<java>int getFirstOptionToShow ()</java>
	<cpp>long getFirstOptionToShow ()</cpp>
	<descr>
	<p>Returns the index of the first displayed option of the group</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	long getFirstOptionToShow() {
		return fFirstOptionToShow;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getTemplateOption</method>
	<java>final public Option getTemplateOption(int index)</java>
	<cpp>Option* getTemplateOption(long index=0)</cpp>
	<descr>
	<p>Group.getTemplateOption(int index) returns a particular template option from the templates list.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	Option* getTemplateOption(long index=0) {
		if(!fTemplateOptions) return NULL;
		return (Option*)fTemplateOptions->get(index);
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getTemplateOptions</method>
	<cpp>SmallArrayList* getTemplateOptions()</cpp>
	<java></java>
	<descr>
	<p>This method returns the template array. In the C++ version, ownership of the returned ptr is NOT transfered to the caller. Thus, the SmallArrayList should not be deleted. Direct access to this list should not be used to bypass setTemplateOption().</p>
	</descr>
	<notes></notes>
	<examples></examples>
	</api>
</page>
</kaleidoc>
	*/
	SmallArrayList* getTemplateOptions() {
		return fTemplateOptions;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>useCacheAsTemplateOptions</method>
	<cpp>void useCacheAsTemplateOptions()</cpp>
	<java>final public void useCacheAsTemplateOptions()</java>
	<descr>
	<p>The Group.useCacheAsTemplateOptions() method moves the options cache into the template list. After that, the template list contains the options built in KD by the designer and the options cache is empty.</p>
	<p>This allows to have many customized options that can be used as templates to build new options by cloning the templates.</p>
	</descr>
	<notes>
	<p>This method should be used with Group.makeOptionFromTemplate() method to clone one of the template options.</p>
	</notes>
	<examples>
	<code>void postRestore (long version){
	Group* g = getGroup();
	g->useCacheAsTemplateOptions();
	...
	</code>
	</examples>
	</api>
</page>
</kaleidoc>
	*/
	void useCacheAsTemplateOptions ();

#ifdef USE_DEPRECATED
	void setTemplateOption(Option* o);
#endif

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setTemplateOption</method>
	<cpp>void setTemplateOption(int index, Option* o)</cpp>
	<java>final public void setTemplateOption(int index, Option o)</java>
	<descr>
	<p>Inserts a particular option as template in the templates list</p>
	</descr>
	<notes></notes>
	<examples></examples>
	</api>
</page>
</kaleidoc>
	*/
	void setTemplateOption(int index, Option* o);

#ifdef DEV_DEBUG
	void dumpOptions();
#endif

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getStoreKey</method>
	<java>String getStoreKey()</java>
	<cpp>char* getStoreKey()</cpp>
	<descr>
	<p>Refer to the setStoreKey() documentation for an explanation</p>
	<p>In the C version, the ownership of the returned string is NOT transferred to the caller.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getStoreKey() {
		return fStoreKey;
	}