Android NDK rb5 文档之 native_activity.h 文件翻译

/**

*Copyright(C)2010TheAndroidOpenSourceProject

*版权（C）2010Android开源工程

*

*LicensedundertheApacheLicense,Version2.0(the"License");

*根据2.0版本Apache许可证授权

*youmaynotusethisfileexceptincompliancewiththeLicense.

*根据本许可证，你可以不使用此文件。

*YoumayobtainacopyoftheLicenseat

*你可以获得许可证的副本在

*

*http://www.apache.org/licenses/LICENSE-2.0

*

*Unlessrequiredbyapplicablelaworagreedtoinwriting,

*softwaredistributedundertheLicenseisdistributedonan"ASIS"BASIS,

*WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.

*除非因适用法律需要或书面同意，

*根据许可证分发的软件是基于"按原样"原则提供，无任何明示的或暗示的保证或条件。

*SeetheLicenseforthespecificlanguagegoverningpermissionsand

*limitationsundertheLicense.

*详见根据许可证许可下，特定语言的管辖权限和限制。

*/

#ifndefANDROID_NATIVE_ACTIVITY_H

#defineANDROID_NATIVE_ACTIVITY_H

#include<stdint.h>

#include<sys/types.h>

#include<jni.h>

#include<android/asset_manager.h>

#include<android/input.h>

#include<android/native_window.h>

#ifdef__cplusplus

extern"C"{

#endif

structANativeActivityCallbacks;

/**

*Thisstructuredefinesthenativesideofanandroid.app.NativeActivity.

*本结构体定义了android.app.NativeActivity的本地部分。

*

*Itiscreatedbytheframework,

*andhandedtotheapplication'snativecodeasitisbeinglaunched.

*它是被框架创建并在应用程序的本地代码运行时传入。

*/

typedefstructANativeActivity{

/**

*Pointertothecallbackfunctiontableofthenativeapplication.

*指向本地应用程序的回调函数表。

*

*Youcansetthefunctionsheretoyourowncallbacks.

*你可以在这里设置你的回调函数。

*

*Thecallbackspointeritselfhereshouldnotbechanged;

*回调指针自身在这里将不会改变；

*

*itisallocatedandmanagedforyoubytheframework.

*由框架为你分配和管理。

*/

structANativeActivityCallbacks*callbacks;

/**

*Theglobalhandleontheprocess'sJavaVM.

*进程的Java虚拟机全局句柄。

*/

JavaVM*vm;

/**

*JNIcontextforthemainthreadoftheapp.

*应用程序主线程用JNI环境。

*

*NotethatthisfieldcanONLYbeusedfromthemainthreadoftheprocess;

*注意这个成员变量仅可以被进程的主线程使用；

*

*thatis,thethreadthatcallsintotheANativeActivityCallbacks.

*即，该进程的主线程调用进入到ANativeActivityCallbacks里。

*/

JNIEnv*env;

/**

*TheNativeActivityJavaclass.

*NativeActivityJava类。

*/

jobjectclazz;

/**

*Pathtothisapplication'sinternaldatadirectory.

*本应用程序的内部数据目录路径。

*/

constchar*internalDataPath;

/**

*Pathtothisapplication'sexternal(removable/mountable)datadirectory.

*本应用程序的外部(可移除的或可安装的)数据目录路径。

*/

constchar*externalDataPath;

/**

*Theplatform'sSDKversioncode.

*平台的SDK版本代码。

*/

int32_tsdkVersion;

/**

*Thisisthenativeinstanceoftheapplication.

*这是应用程序的本地实例。

*

*Itisnotusedbytheframework,

*butcanbesetbytheapplicationtoitsowninstancestate.

*它是不能被框架使用，但是可以被应用程序设置它自己的实例状态。

*/

void*instance;

/**

*PointertotheAssetManagerinstancefortheapplication.

*指向应用程序资产管理器实例。

*

*Theapplicationusesthistoaccessbinaryassetsbundledinsideitsown.apkfile.

*应用程序使用它来存取包在它自己.apk文件里面的二进制资产。

*/

AAssetManager*assetManager;

}ANativeActivity;

/**

*Thesearethecallbackstheframeworkmakesintoanativeapplication.

*这些回调使框架转变成一个本地应用程序。

*

*Allofthesecallbackshappenonthemainthreadoftheapplication.

*这些回调全部发生在应用程序的主线程上。

*

*Bydefault,allcallbacksareNULL;

*默认情况下，全部回调都是NULL;

*settoapointertoyourownfunctiontohaveitcalled.

*设置指向你自己的函数允许被调用。

*/

typedefstructANativeActivityCallbacks{

/**

*NativeActivityhasstarted.

*NativeActivity已经启动。

*SeeJavadocumentationforActivity.onStart()formoreinformation.

*看Java文档中的Activity.onStart()的更多信息。

*注：该方法说明了将要显示给用户的活动。

*/

void(*onStart)(ANativeActivity*activity);

/**

*NativeActivityhasresumed.

*NativeActivity已经(中断后)继续。

*SeeJavadocumentationforActivity.onResume()formoreinformation.

*看Java文档中的Activity.onResume()的更多信息。

*注：用户可以开始与活动进行交互时会调用该方法。这个方法非常适合开始播放动画和音乐。

*/

void(*onResume)(ANativeActivity*activity);

/**

*FrameworkisaskingNativeActivitytosaveitscurrentinstancestate.

*框架寻问NativeActivity去保存它的当前实例状态。

*

*SeeJavadocumentationforActivity.onSaveInstanceState()formoreinformation.

*看Java文档中的Activity.onSaveInstanceState()的更多信息。

*注：Android调用该方法的作用是让活动可以保存每个实例的状态，如光标在文本字段中的位置。

*

*Thereturnedpointerneedstobecreatedwithmalloc();

*返回值指针是用malloc()创建的；

*

*theframeworkwillcallfree()onitforyou.

*框架将为你调用free()释放它。

*

*YoualsomustfillinoutSizewiththenumberofbytesintheallocation.

*你还必须用outSize来得到分配的字节数量。

*

*Notethatthesavedstatewillbepersisted,

*soitcannotcontainanyactiveentities(pointerstomemory,filedescriptors,etc).

*注意保存状态将是持续的，所以它不能包含任何活动实体(指向内存、文件描述，等等)。

*/

void*(*onSaveInstanceState)(ANativeActivity*activity,

size_t*outSize);

/**

*NativeActivityhaspaused.

*NativeActivity已经暂停。

*

*SeeJavadocumentationforActivity.onPause()formoreinformation.

*看Java文档中的Activity.onPause()的更多信息。

*注：活动将要进入后台时会运行该方法，活动进入后台的原因通常是在前台启动了另一个活动。

*　　还应该在该方法中保存程序的持久性状态，如正在编辑的数据库记录。

*/

void(*onPause)(ANativeActivity*activity);

/**

*NativeActivityhasstopped.

*NativeActivity已经停止。

*

*SeeJavadocumentationforActivity.onStop()formoreinformation.

*看Java文档中的Activity.onStop()的更多信息。

*注：用户无需看到某个活动，或者在一段时间内不需要某个活动时，可以调用该方法。

*　　如果内存不足，可能永远都不会调用该方法，系统可能只是终止进程。

*/

void(*onStop)(ANativeActivity*activity);

/**

*NativeActivityisbeingdestroyed.

*NativeActivity正在被销毁。

*

*SeeJavadocumentationforActivity.onDestroy()formoreinformation.

*看Java文档中的Activity.onDestroy()的更多信息。

*注：销毁活动前会调用该方法。

*　　如果内存不足，可能永远都不会调用该方法，系统可能只是终止进程。

*/

void(*onDestroy)(ANativeActivity*activity);

/**

*FocushaschangedinthisNativeActivity'swindow.

*在这个NativeActivity的窗口里焦点已经改变。

*Thisisoftenused,forexample,topauseagamewhenitlosesinputfocus.

*这是通常用来，例如，当一个游戏丢失输入焦点时暂停。

*/

void(*onWindowFocusChanged)(ANativeActivity*activity,

inthasFocus);

/**

*Thedrawingwindowforthisnativeactivityhasbeencreated.

*这个本地活动已经创建了图形窗口。

*

*Youcanusethegivennativewindowobjecttostartdrawing.

*你可以使用特定的本地窗口对象开始绘画。

*/

void(*onNativeWindowCreated)(ANativeActivity*activity,

ANativeWindow*window);

//

*Thedrawingwindowforthisnativeactivityhasbeenresized.

*这个本地活动已经重设图形窗口大小。

*

*Youshouldretrievethenewsizefromthewindowandensurethat

*yourrenderinginitnowmatches.

*你将重新得到窗口的新大小并且保证你的绘制现在用它相一致。

*/

void(*onNativeWindowResized)(ANativeActivity*activity,

ANativeWindow*window);

/**

*Thedrawingwindowforthisnativeactivityneedstoberedrawn.

*这个本地活动需要重绘图形窗口。

*

*Toavoidtransientartifactsduringscreenchanges(suchresizingafterrotation),

*applicationsshouldnotreturnfromthisfunction

*untiltheyhavefinisheddrawingtheirwindowinitscurrentstate.

*为预防短暂的错失在屏幕改变期间(在交替之后重新恢复到应有尺寸)，

*应用程序将不能从这个函数返回直到它们用它们的当前状态绘画它们的窗口完成。

*/

void(*onNativeWindowRedrawNeeded)(ANativeActivity*activity,

ANativeWindow*window);

/**

*Thedrawingwindowforthisnativeactivityisgoingtobedestroyed.

*这个本地活动将要销毁图形窗口。

*

*YouMUSTensurethat

*youdonottouchthewindowobjectafterreturningfromthisfunction:

*你必须确保你没有触摸窗口对象在从这个函数返回后：

*

*inthecommoncaseofdrawingtothewindowfromanotherthread,

*thatmeanstheimplementationofthiscallbackmustproperlysynchronize

*withtheotherthreadtostopitsdrawingbeforereturningfromhere.

*在窗口出自其它线程的共同绘图情况中，意味着该回调实现必须妥善同步，在从这里退出之前其它线程停止它们的绘图。

*/

void(*onNativeWindowDestroyed)(ANativeActivity*activity,

ANativeWindow*window);

/**

*Theinputqueueforthisnativeactivity'swindowhasbeencreated.

*这个本地活动窗口的输入队列已经创建。　

*

*Youcanusethegiveninputqueuetostartretrievinginputevents.

*你可以使用给定的输入队列开始检索输入事件。

*/

void(*onInputQueueCreated)(ANativeActivity*activity,

AInputQueue*queue);

/**

*Theinputqueueforthisnativeactivity'swindowisbeingdestroyed.

*这个本地活动窗口的输入队列已经销毁。

*

*Youshouldnolongertrytoreferencethisobjectuponreturningfromthisfunction.

*一旦从该函数返回你将不能再试图引用这个对象了。

*/

void(*onInputQueueDestroyed)(ANativeActivity*activity,

AInputQueue*queue);

/**

*Therectangleinthewindowinwhichcontentshouldbeplacedhaschanged.

*窗口内容矩形被放置改变。

*/

void(*onContentRectChanged)(ANativeActivity*activity,

constARect*rect);

/**

*ThecurrentdeviceAConfigurationhaschanged.

*当前设备AConfiguration已发生改变。

*

*ThenewconfigurationcanberetrievedfromassetManager.

*新的配置可以从activity->assetManager中检索到。

*/

void(*onConfigurationChanged)(ANativeActivity*activity);

/**

*Thesystemisrunninglowonmemory.

*系统正在用尽内存。

*

*Usethiscallbacktoreleaseresourcesyoudonotneed,

*tohelpthesystemavoidkillingmoreimportantprocesses.

*使用这个回调去释放你不需要的资源，以免系统杀死更多重要的进程。

*/

void(*onLowMemory)(ANativeActivity*activity);

}ANativeActivityCallbacks;

/**

*Thisisthefunctionthat

*mustbeinthenativecodetoinstantiatetheapplication'snativeactivity.

*必须在本地代码中实例化应用程序的本地活动。

*

*Itiscalledwiththeactivityinstance(seeabove);

*它是被活动实例调用的(参见上文)；

*

*ifthecodeisbeinginstantiatedfromapreviouslysavedinstance,

*thesavedStatewillbenon-NULLandpointtothesaveddata.

*如果正在被实例化用之前保存的实例，savedState参数值将非NULL且指向已保存的数据。

*

*Youmustmakeanycopyofthisdatayouneed--

*itwillbereleasedafteryoureturnfromthisfunction.

*你必须备份savedState中你需要的数据--它将在从这个函数中返回后释放。

*/

typedefvoidANativeActivity_createFunc(ANativeActivity*activity,

void*savedState,

size_tsavedStateSize);

/**

*ThenameofthefunctionthatNativeInstancelooksforwhenlaunchingitsnativecode.

*当启动它的本地代码时，NativeInstance寻找这个函数名。

*

*Thisisthedefaultfunctionthatisused,

*youcanspecify"android.app.func_name"stringmeta-datain

*yourmanifesttouseadifferentfunction.

*被用作默认函数，你可以在你的AndroidManifest.xml里的activity标签下用

*<meta-dataandroid:name="android.app.func_name"android:value="替换的函数名"/>

*明确说明使用一个不同的函数。

*/

externANativeActivity_createFuncANativeActivity_onCreate;

/**

*Finishthegivenactivity.

*结束给定的活动。

*

*Itsfinish()methodwillbecalled,

*causingittobestoppedanddestroyed.

*它的finish()方法将是被调用，导致它停止且销毁。

*

*Notethatthismethodcanbecalledfrom*any*thread;

*注意该方法可以被任何线程调用；

*

*itwillsendamessagetothemainthreadoftheprocess

*wheretheJavafinishcallwilltakeplace.

*它将发送一个消息到进程的主线程，在那里Java结束调用将发生。

*/

voidANativeActivity_finish(ANativeActivity*activity);

/**

*Changethewindowformatofthegivenactivity.

*改变给定活动的窗口样式。

*

*CallsgetWindow().setFormat()ofthegivenactivity.

*调用给定活动的getWindow().setFormat()。

*

*Notethatthismethodcanbecalledfrom*any*thread;

*注意该方法可以被任何线程调用；

*

*itwillsendamessagetothemainthreadoftheprocess

*wheretheJavafinishcallwilltakeplace.

*它将发送一个消息到进程的主线程，在那里Java结束调用将发生。

*/

voidANativeActivity_setWindowFormat(ANativeActivity*activity,

int32_tformat);

/**

*Changethewindowflagsofthegivenactivity.

*改变给定活动的窗口标志。

*

*CallsgetWindow().setFlags()ofthegivenactivity.

*调用给定活动的getWindow().setFlags()。

*

*Notethatthismethodcanbecalledfrom*any*thread;

*注意该方法可以被任何线程调用；

*

*itwillsendamessagetothemainthreadoftheprocess

*wheretheJavafinishcallwilltakeplace.

*它将发送一个消息到进程的主线程，在那里Java结束调用将发生。

*

*Seewindow.hforflagconstants.

*看window.h中的标志常量。

*/

voidANativeActivity_setWindowFlags(ANativeActivity*activity,

uint32_taddFlags,

uint32_tremoveFlags);

/**

*FlagsforANativeActivity_showSoftInput;

*ANativeActivity_showSoftInput的标志；

*

*seetheJavaInputMethodManagerAPIfordocumentation.

*看Java中关于InputMethodManagerAPI的文档。

*/

enum{

ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT=0x0001,

ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED=0x0002,

};

/**

*ShowtheIMEwhileinthegivenactivity.

*在给定活动里显示输入法时。

*

*CallsInputMethodManager.showSoftInput()forthegivenactivity.

*为给定活动调用InputMethodManager.showSoftInput()。

*

*Notethatthismethodcanbecalledfrom*any*thread;

*注意该方法可以被任何线程调用；

*

*itwillsendamessagetothemainthreadoftheprocess

*wheretheJavafinishcallwilltakeplace.

*它将发送一个消息到进程的主线程，在那里Java结束调用将发生。

*/

voidANativeActivity_showSoftInput(ANativeActivity*activity,uint32_tflags);

/**

*FlagsforANativeActivity_hideSoftInput;

*ANativeActivity_hideSoftInput的标志；

*

*seetheJavaInputMethodManagerAPIfordocumentation.

*看Java中关于InputMethodManagerAPI的文档。

*/

enum{

ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY=0x0001,

ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS=0x0002,

};

/**

*HidetheIMEwhileinthegivenactivity.

*在给定活动里隐藏输入法时。

*

*CallsInputMethodManager.hideSoftInput()forthegivenactivity.

*为给定活动调用InputMethodManager.hideSoftInput()。

*

*Notethatthismethodcanbecalledfrom*any*thread;

*注意该方法可以被任何线程调用；

*

*itwillsendamessagetothemainthreadoftheprocess

*wheretheJavafinishcallwilltakeplace.

*看Java中关于InputMethodManagerAPI的文档。

*/

voidANativeActivity_hideSoftInput(ANativeActivity*activity,uint32_tflags);

#ifdef__cplusplus

};

#endif

#endif//ANDROID_NATIVE_ACTIVITY_H