kr_group.h

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

	void resetFocusIndex();

	long getActivateStamp() {
		return fActivateStamp;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>makeOptionFromTemplate</method>
	<java>final public Option makeOptionFromTemplate(int index) throws Throwable</java>
	<cpp>Option* makeOptionFromTemplate(int index)</cpp>
	<descr>
	<p>This method is used in a populator to instantiate a new Option by cloning one of the template Option designed by the Kaleido Designer. It makes a shallow copy of the template option.</p>
	<note>It is very important to notice that only pointers are copied. Thus referenced objects are shared between the template options and all options generated by makeOptionFromTemplate(). </note>
	<p>The following members are copied from the template:</p>

	<code>	BgSrcOff: the url of the background image of the deselected state
	BgSrcOn: the url of the background image of the selected state
	The bindings on accept set of groups
	The bindings on focus set of groups
	The option param coming from the bsh file
	ImgSrcOff: the url of the image of the deselected state
	ImgSrcOn: the url of the image of the selected state
	The Link parameters used in the doAccept() method.</code>

	<p>Accessors of some of the previous fields are "template aware":</p>

	<code>void Option::setBgSrcOn(char* bgsrcOn)
	void Option::setBgSrcOff(char* bgsrcOn)
	void setOptionParam(char* optionParam)
	void setImgSrcOff(char* imgSrc)
	void setImgSrcOn(char* imgSrc)
	void setLink(char* link, char* accept, char* useragent)</code>

	<p>These calls duplicate values to get the property of the fields, so the setters are safe.
	Only bindings are not duplicated. For these reasons, setBindingsOnAccept() and setBindingsOnFocus() should NOT be called on options created by makeOptionFromTemplate(). These method can be called on deep clone of the template option. KRuntime does not provide deep clone.</p>
	<p>Some Option fields are not duplicated. It can be done "by hand" if necessary:</p>
	<code>
	int accessKey = getGroup()-&gt;getTemplateOption()-&gt;getAccessKey() ;
	if (accessKey)
	o-&gt;setAccessKey(accessKey) ;
	</code>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	Option* makeOptionFromTemplate(int index=0);

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getOptions</method>
	<java>SmallArrayList getOptions()</java>
	<cpp>SmallArrayList* getOptions()</cpp>
	<descr>
	<p>Returns the group cache as an Options list.
	This method does NOT ask the associated populator to build or update any missing or outdated option.
	In this case, the generated option is systematically cached at the group level.
	It would be a bad idea to browse a big list using getOption() since it would increase the cache.
	The populator should be directly called in this case.</p>
	<p>In the C version, ownership of the list object is kept by the Group. </p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	SmallArrayList* getOptions() {
		return fOptions;
	}


	void setOptions(SmallArrayList* options) {
		SAFE_DELETE(fOptions);
		fOptions = options;
	}

	// mainly used for unit tests
void addOption(Option* o) {
		if(fOptions==NULL)
			fOptions = new SmallArrayList(10);
		int index = fOptions->add(o);
		adapt4Group(o, index);
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getOption</method>
	<java>final public Option getOption(int index) throws Throwable</java>
	<cpp>Option* getOption(long index)</cpp>
	<descr>
	<p>Returns the Option at a particular index in the group cache. Ownership of options returned by Group.getOption() is kept by the Group. If necessary, this method asks the associated populator to build or update any missing or outdated option. In this case, the generated option is systematically cached at the group level. It is not a good idea to browse a large list using getOption() since it would increase the cache's size. The populator should rather be directly called in this case.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	Group* setOption(long index, Option* o) ;

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>isPersistentFocus</method>
	<java>boolean isPersistentFocus()</java>
	<cpp>boolean isPersistentFocus()</cpp>
	<descr>
	<p>Makes the focus index of the group persistent. When the focus changes, it is kept in the global Store. When resetFocusIndex() is called on a group with the same group name - this is done for each created group in the activate phase if not already one-, this group gets its focus back.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	boolean isPersistentFocus() {
		return fPersistentFocus;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setPersistentFocus</method>
	<java>void setPersistentFocus(boolean PersistentFocus)</java>
	<cpp>void setPersistentFocus(boolean PersistentFocus)</cpp>
	<descr>
	<p>Makes the Group store its focus index in the global store and retrieve it later. The key used is "_groupFocus-" concatenated to the name of the group. You can set this value before loading the layout to make the group have a predefined focus. Example:</p>
	<code>char* key = getContext()->getTmpBuffer() ;
	sprintf(key,"_groupFocus-Group1");
	getContext()->replaceIntData(key, 3);</code>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setPersistentFocus(boolean b) {
		fPersistentFocus = b;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setInitialFocusIndex</method>
	<java>void setInitialFocusIndex(int focusIndex)</java>
	<cpp>void setInitialFocusIndex(long focusIndex)</cpp>
	<descr>
	<p>Sets the Group's initial focus. This is normally set in Kaleido Design.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setInitialFocusIndex(long v) {
		fInitialFocusIndex = v;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getInitialFocusIndex</method>
	<java>long getInitialFocusIndex()</java>
	<cpp>long getInitialFocusIndex()</cpp>
	<descr>
	<p>Returns the initial focus.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	long getInitialFocusIndex() {
		return fInitialFocusIndex;
	}

#ifdef USE_DEPRECATED
	long getInitialFocusIndexOnFocus() {
		return getInitialFocusIndex();
	}
#endif

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getFocusKey</method>
	<cpp>char* getFocusKey(char* name=NULL)</cpp>
	<java>public final String getFocusKey(String name)</java>
	<descr>
	<p>Returns the key used by the Group.setStoreKey() to index the focus in the Store. 
	This key can be used to mimic this call to preset the value. 
	The 'name' parameter is usually the group name, which is used if null is passed as parameter.
	If null is passed as parameter, The 'name' parameter is set to the group name.
	</p>
	<xref>GlobalStore</xref>
	<p>In the C version, the 'name' ownership is NOT transfered to the Group. The ownership of the returned 'key' is NOT transferred to the caller. This means the value should be strduped to survive.</p>
	</descr>
	<notes></notes>
	<examples></examples>
	</api>
</page>
</kaleidoc>
	*/
	virtual char* getFocusKey(char* name);

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>loadFocus</method>
	<cpp>virtual long loadFocus()</cpp>
	<java>public int loadFocus()</java>
	<descr>
	<p>This is an internal method that loads the focus of the group from the store if the focus is persistent. This method can be overriden to modify the way the focus is made persistent.</p>
	</descr>
	<notes></notes>
	<examples></examples>
	</api>
</page>
</kaleidoc>
	*/
	virtual long loadFocus();

	void setFocusIndexPercent(long percent, boolean useStore, boolean setShouldBeRendered);

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>storeFocus</method>
	<cpp>virtual void storeFocus(long index)</cpp>
	<java></java>
	<descr>
	<p>This method can be overriden to modify the way the focus is made persistent. The 'index' parameter is usually Group.getFocusIndex().</p>
	</descr>
	<notes></notes>
	<examples></examples>
	</api>
</page>
</kaleidoc>
	*/
	virtual void storeFocus(long index);

	long getStamp4Options() {
		return fStamp4Options;
	}

	void setStamp4Options(unsigned long v) {
		fStamp4Options = v;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>setFocusIndex</method>
	<java>void setFocusIndex(int focusIndex)</java>
	<cpp>void setFocusIndex(long focusIndex)</cpp>
	<descr>
	<p>Sets the Group's current focus. Initially, the group gets the initial focus as set in Kaleido Design by the Designer.</p>
	<p>Option.focusOff() is called on the option that looses the focus. Option.focusOn() is also called on the option that gets the focus.</p>
	<p>This is a low level accessors that do not handle potentially dimmed options. For this reasons, Group.moveFocusIndexToUndimmed() should be used preferably.</p>

	<note>Note that an activate phase is necessary to make this change be taken into account.</note>
	<note>This method is a low level accessor that does not check whether the target option is dimmed or not. Group.moveFocusIndexToUndimmed() should be used instead for this purpose.</note>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void setFocusIndex(long focusIndex);
	void setFocusIndex(long focusIndex, boolean useStore, boolean setShouldBeRendered);

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getFocusIndex</method>
	<java>long getFocusIndex()</java>
	<cpp>long getFocusIndex()</cpp>
	<descr>
	<p>Returns the current focus index.</p>
	<include>FocusSpecialValues.inc.xml</include>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	long getFocusIndex() {
		return fFocusIndex;
	}

	void setName(char* name) {
		ASSERT_MEMORY_OWNERSHIP(this, name);

		SAFE_FREE(fName);
		fName = name;
	}

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>render</method>
	<java>public String render() throws Throwable</java>
	<cpp>void render()</cpp>
	<descr>
	<p>This method is called by Kaleido Runtime to render the Group on the Screen. Overriding this method gives complete control on the group's rendering. This allows to implement complex behaviors that could not be achieved with the combining of Group and View properties.</p>
	<p>The basic Group object encapsulates many properties that may be useful to develop other plug-ins.</p>
	</descr>
	<examples>
	<code>void render()  {

	long focus=getFocusIndex();

	if (focus==0)
	getView()-&gt;setBorderBegin(0);
	else if (focus==getNbOptionInCache())
	getView()-&gt;setBorderEnd(0);
	else {
	getView()-&gt;setBorderBegin(1);
	getView()-&gt;setBorderEnd(1);
	}

	Group::render();
	}</code>
	</examples>
	</api>
</page>
</kaleidoc>
	*/
	virtual void render() ;

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>moveFocusIndexToUndimmed</method>
	<cpp>void moveFocusIndexToUndimmed(long index, long step)</cpp>
	<java>public final void moveFocusIndexToUndimmed(int index, int step) throws Throwable</java>
	<descr>
	<p>Sets the Group's focus to the specified index and moves the focus in the step direction until the focus option is not dimmed.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void moveFocusIndexToUndimmed(long index, long step);

	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>moveFocusIndexToUndimmed</method>
	<cpp>void moveFocusIndexToUndimmed(long i, boolean useStore, long step)</cpp>
	<java></java>
	<descr>
	<p>Moves the focus to the next undimmed option, starting at index i, adding steps step. useStore is used as second parameter for Group.setFocusIndex() which remembers the focus if Group.isPersistentFocus() is true.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	void moveFocusIndexToUndimmed(long i, boolean useStore, long step);

#ifdef DEV_CONSISTENCY
	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getJitMapperVersion</method>
	<java></java>
	<cpp>char* getJitMapperVersion ()</cpp>
	<descr>
	<p>Returns a string containing the version number of the plug-in that was available to generate the bin file.</p>
	<p>In the C version, the ownership of the returned object is not transferred to the caller.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getJitMapperVersion() { return fJitMapperVersion; }
	/*
	<kaleidoc>
<filename>Group</filename>
<page>
<api>
	<class>Group</class>
	<method>getPopulatorVersion</method>
	<java></java>
	<cpp>char* getPopulatorVersion ()</cpp>
	<descr>
	<p>Returns a string containing the version number of the plug-in that was available to generate the bin file.</p>
	<p>In the C version, the ownership of the returned string is not transferred to the caller.</p>
	</descr>
	</api>
</page>
</kaleidoc>
	*/
	char* getPopulatorVersion() { return fPopulatorVersion; }
#endif // def DEV_CONSISTENCY

};

//
typedef Group* pGroup ;
typedef pGroup (*GroupInstanciator)(GContext* newGContext) ;

#endif // ndef __KR_GROUP__