تست و دیباگ پروژه یکی از مهم‌ترین فرایندهای توسعه‌ی اپلیکیشن اندرویدی به شمار می‌رود. در این فرایند پروژه روی یک دستگاه حقیقی یا مجازی اندرویدی اجرا می‌شود تا توسعه‌دهنده بتواند کارکرد کدهای خود را بررسی کرده و نواقص احتمالی را برطرف کند.
در این آموزش قصد دارم نحوه‌ی کار با شبیه ساز (امولاتور) اندروید استودیو و همچنین اضافه کردن و اجرای دیوایس‌ها از طریق AVD را بررسی کنم.

شبیه ساز یا Emulator چیست؟

به نام خدا. در زمان نگارش این مبحث آموزشی، اندروید ۱۲ به عنوان آخرین نسخه‌ی پایدار این سیستم‌عامل منتشر شده و حدود ۱۲% از کل دیوایس‌های اندرویدی را پوشش می‌دهد. این یعنی هنوز درصد قبل توجهی از موبایل‌ها، تبلت‌ها و دستگاه‌های اندرویدی دیگر از نسخه‌های پایین‌تر استفاده می‌کنند.
بنابراین شما به عنوان یک برنامه نویس و توسعه دهنده‌ی اندروید لازم است پروژه‌ی اندرویدی خود را روی چندین دستگاه اندرویدی با نسخه‌های متفاوت تست کنید تا مطمئن شوید اپلیکیشن روی اکثر دستگاه‌هایی که در اختیار مردم قرار دارد عملکرد صحیحی خواهد داشت.
به عبارت دیگر شما باید چندین گوشی و تبلت خریداری کنید تا بتوانید پروژه را روی تک تک آنها بررسی کنید که علاوه بر افزایش هزینه، چالش‌های خاص خود را به همراه دارد.
اینجاست که امولاتور یا شبیه سازها وارد میدان شده و کار را بسیار ساده‌تر می‌کنند. با استفاده از شبیه ساز می‌توان هر تعداد از دیوایس‌های مجازی اندرویدی را روی کامپیوتر نصب و اجرا کرد. یعنی دیگر خبری از دیوایس فیزیکی و مشکلات اتصال آن به اندروید استودیو نیست.
با استفاده از امولاتور به راحتی می‌توانید چندین دیوایس مجازی با نسخه‌ی سیستم عامل و اندازه‌ی صفحه نمایش مختلف ایجاد و پروژه‌ی خود را روی آنها تست و دیباگ کنید.
شبیه سازهای مختلفی برای اندروید ساخته شده که روی سیستم‌عامل‌های محبوب مانند ویندوز، لینوکس و مک قابل استفاده هستند. درحال حاضر Genymotion، BlueStacks و MEMu جزء گزینه‌های مطرح به شمار می‌روند.

چرا AVD؟

در اندروید استودیو از همان ابتدای کار یک امولاتور داخلی در اختیار توسعه‌دهندگان قرار گرفته بود که امکان مدیریت دیوایس‌ها با استفاده از ابزار AVD فراهم شده است.
بااینحال از سال ۱۳۹۵ تا اوایل ۱۴۰۱ با توجه به مزایایی که Genymotion نسبت به AVD داشت (مانند سرعت بالاتر و حجم کم دیوایس‌ها) شخصاً ترجیح می‌دادم از جنی موشن استفاده کنم.
اما در ماه‌های اخیر سیاست جنی موشن در خصوص ارائه‌ی نسخه‌ی دسکتاپ این شبیه ساز تغییراتی داشته که مهم‌ترین آنها عدم انتشار API برای نسخه‌های جدید اندروید و اعمال محدودیت ۱ ماهه برای نسخه‌ی رایگان (Personal) هستند. از این به بعد تمرکز تیم Genymotion بر ارائه‌ی خدمات بر بستر Cloud است که هزینه‌های آن برای برنامه نویسان ایرانی بسیار بالاست.
در این مدت مشکلات AVD مخصوصا مساله‌ی سرعت اجرا هم تا حدود زیادی رفع شد و با توجه به شرایط فعلی، استفاده از شبیه ساز داخلی اندروید استودیو منطقی‌ترین گزینه محسوب می‌شود. همین مساله باعث شد آموزش کار با امولاتور داخلی اندروید استودیو و AVD را تهیه کنم.

نصب امولاتور اندروید استودیو

امولاتور اندروید استودیو به صورت پیش‌فرض فعال نیست و باید از طریق SDK Manager نصب شود. همانطور که در آموزش نصب و راه اندازی اندروید استودیو گفته شد، امکان نصب آفلاین گزینه‌های Emulator و HAXM وجود ندارد و صرفا باید به صورت آنلاین نصب انجام شود.
همچنین هنگام نصب اندروید استودیو باید گزینه‌ی Android Virtual Device انتخاب شده باشد در غیر اینصورت امکان استفاده از دیوایس مجازی یا AVD وجود نخواهد داشت:

پس از اطمینان از برقراری ارتباط اینترنت و تغییر IP برای عبور از تحریم ایران، SDK Manager را باز می‌کنم. اگر برای تغییر IP در اندروید استودیو نیاز به راهنمایی دارید این آموزش را مطالعه کنید.
گزینه Android Emulator را انتخاب و تایید می‌کنم تا دانلود و نصب آن شروع شود.

یک ابزار جانبی با نام Intel x86 Emulator Accelerator (Haxm) در لیست SDK وجود دارد که استفاده از آن بر روی پردازنده‌های اینتل باعث افزایش سرعت شبیه ساز می‌شود. بنابراین در صورتی که پردازنده شما Intel باشد حتما این ابزار را هم نصب کنید.

در این مرحله حداکثر میزانی از RAM که به امولاتور باید اختصاص داده شود را تعیین می‌کنیم که من همان عدد پیش‌فرض یعنی ۲ گیگابایت را انتخاب می‌کنم. البته این عدد بعداً هم قابل تغییر است.

نصب HAXM هم به پایان رسید و حالا می‌توانیم از شبیه ساز و AVD استفاده کنیم.
اگر به یاد داشته باشید قبلا در جلسه‌ی آموزش نصب اندروید استودیو توضیح دادیم که در SDK Platforms برای هر API چند System image مختلف وجود دارد که این سیستم ایمیج‌ها برای شبیه ساز داخلی اندروید استودیو استفاده می‌شود:

همانطور که در تصویر فوق مشاهده می‌کنید برای Android 12 به تعداد ۹ عدد System Image وجود دارد. توضیحات مربوط به هر سیستم ایمیج قبلا در قسمت توضیحات SDK در آموزش نصب اندروید استودیو قید شده بنابراین نیازی به تکرار نیست.
امکان دانلود و نصب هرکدام از سیستم ایمیج‌ها از طریق SDK Manager وجود دارد اما برای جلوگیری از انتخاب گزینه اشتباه توصیه می‌کنم دانلود را در محیط AVD انجام دهید. در AVD سیستم ایمیج مناسب شما در تب Recommended قرار می‌گیرد و از دانلود سیستم ایمیج‌های غیر ضروری و حجم بالا جلوگیری می‌کند.
گزینه Device Manager را از منوی تولبار یا نوار سمت راست اندروید استودیو انتخاب می‌کنم:

پنجره Device Manager باز شد:

در دیوایس منیجر دو تب Virtual (مجازی) و Physical (فیزیکی) وجود دارد. تب Virtual برای مدیریت دیوایس‌های مجازی استفاده می‌شود. در حال حاضر هیچ دیوایس مجازی در لیست وجود ندارد.
روی دکمه Create device یا لینک Create Virtual device کلیک می‌کنم تا پنل ساخت دیوایس مجازی باز شود:

در سمت چپ، دیوایس‌ها دسته‌بندی شده که در حالت پیش‌فرض گزینه Phone و یکی از دیوایس‌های آن انتخاب شده است. دیوایس‌های مختلفی در لیست وجود دارد که بر اساس متغیرهایی مانند سایز صفحه نمایش و رزولوشن آن مشخص شده‌اند.
من فعلا سایز خاصی مدنظرم نیست بنابراین همین دیوایس پیش فرض را انتخاب می‌کنم برای مرحله بعد.
دیوایسی که انتخاب شده دارای برنامه Play Store است بنابراین سیستم ایمیجی دانلود خواهد شد که از پلی استور پشتیبانی می‌کند.

در این مرحله باید نسخه‌ی system image مدنظر خود را انتخاب کنیم. برای مثال من قصد دارم دیوایس را با API 31 یعنی Android 12 بسازم. بنابراین همین API را باید انتخاب کنم اما در حال حاضر این API و تمامی API های دیگر یک گزینه دانلود مقابلشان قرار داده شده که نشان می‌دهد سیستم ایمیج هیچکدام دانلود و نصب نشده.
روی گزینه Download اندروید ۱۲ کلیک می‌کنم:

دانلود system image آغاز شد. خبر خوب اینکه مانند سایر ابزار SDK و برخلاف Emulator و HAXM فایل‌های مربوط به system image را می‌توان در خارج از محیط اندروید استودیو دانلود و به صورت آفلاین به SDK اضافه کرد.
با توجه به حجم بالای سیستم ایمیج‌ها (حدود ۱٫۵ گیگابایت) و لزوم استفاده از ابزار تغییر IP احتمال شکست دانلود بالاست بنابراین توصیه می‌کنم لینک فایل سیستم ایمیج را از قسمت بالا کپی کرده و با استفاده از یک برنامه مدیریت دانلود، دریافت کنید.
هرچند بازهم برای دانلود فایل نیاز به استفاده از ابزار تغییر IP وجود دارد اما در صورت استفاده از برنامه‌های مدیریت دانلود، چنانچه فرایند دانلود در هر نقطه قطع شود، می‌توان مجدد دانلود را از همان نقطه ادامه داد در حالی که در اندروید استودیو دانلود از ابتدا آغاز خواهد شد.
اگر همچنان قصد دارید دانلود به صورت خودکار و در محیط اندروید استودیو انجام شود فقط کافیست صبر کنید تا دانلود فایل به اتمام برسد.
اما من ترجیح می‌دهم فایل را جداگانه دانلود و سپس به محل نصب SDK منتقل کنم. بنابراین لینک فایل را کپی و فرایند دانلود را متوقف می‌کنم.
پوشه SDK را باز می‌کنم:

مشاهده می‌کنید یک پوشه با نام system-images در SDK من وجود دارد. علت اینکه این پوشه قبلا ساخته شده این است که من در قسمت قبل یک سیستم ایمیج را برای دانلود انتخاب کردم و فرایند دانلود آغاز شد.
به محض شروع دانلود، پوشه‌های لازم برای قرارگیری سیستم ایمیج‌ها ایجاد می‌شود حتی اگر دانلود متوقف شود.
بنابراین اگر فایل سیستم ایمیج را قبلا دانلود کرده‌اید یا لینک آن را در اختیار دارید و نیازی به انجام مراحل قبل برای دریافت لینک دانلود ندارید، این پوشه هم خودکار ساخته نشده و خودتان باید آنرا با همین نام ایجاد کنید.

وارد پوشه system-images می‌شوم:

یک پوشه با نام android-31 وجود دارد که مربوط به Android 12 است که در AVD برای دانلود انتخاب کرده بودم. داخل این پوشه به ترتیب به این شکل ساخته شده:

حالا کافیست پوشه x86_64 را حذف کرده و پوشه‌ای با همین نام که در فایل زیپ سیستم ایمیج قرار دارد را جایگزین کنم. نام فایلی که من دانلود کردم x86_64-31_r09.zip است. در نامگذاری فایل سیستم ایمیج از جزئیات آن استفاده شده است.
X86_64 یعنی دیوایسی که با این سیستم ایمیج ساخته شود از اپلیکیشن‌های ۶۴ بیتی هم پشتیبانی می‌کند. عدد ۳۱ مربوط به نسخه API است و r09 یعنی فایل سیستم فعلی نهمین نسخه بروزرسانی شده از این سیستم ایمیج است.
به این ترتیب می‌توان یک سیستم ایمیج را بدون نیاز به دانلود آن در محیط اندروید استودیو نصب کرد.
در اینجا چون دانلود سیستم ایمیج اندروید ۱۲ برای لحظه‌ای آغاز شده بود، با اینکه آنرا متوقف کردم، تمامی پوشه‌های مربوط به آن به طور خودکار ساخته شد. اما اگر به هر دلیلی این فرایند انجام نشود، این پوشه‌ها باید به صورت دستی ایجاد شود.
برای مثال این سیستم ایمیج مربوط به API 31 بود بنابراین نام پوشه اصلی آن android-31 است. دیوایس Pixel 2 که در AVD انتخاب کردیم از نوعی بود که از Play Store پشتیبانی می‌کرد بنابراین پوشه بعدی با نام google_apis_playstore ساخته شده. اگر دیوایس از نوعی باشد که پلی استور را پشتیبانی نمی‌کند پوشه را با نام google_apis می‌سازیم.

پوشه x86_64 که از فایل زیپ دانلود شده خروجی گرفتم را جایگزین این پوشه کرده و به پنجره ساخت دیوایس برمی‌گردم. با توجه به اینکه سیستم ایمیج به صورت آفلاین نصب شد یکبار با استفاده از دکمه Refresh لیست سیستم ایمیج‌ها را بروز می‌کنم:

مشاهده می‌کنید API 31 نصب و گزینه Download حذف شده است. همچنین با انتخاب این API دکمه Next فعال شده و می‌توان به مرحله بعد رفت.

در این مرحله جزئیات دیوایس مجازی را می‌توان تغییر داد. مانند نام دیوایس و وضعیت افقی یا عمودی بودن دیوایس هنگام اجرا. با انتخاب گزینه Show Advanced Settings سایر تنظیمات فعال می‌شود.
با کلیک روی Finish دیوایس ساخته شده و به لیست دیوایس‌های مجازی من اضافه می‌شود:

در قسمت Actions چهار گزینه برای هر دیوایس وجود دارد. گزینه اول برای استارت دیوایس است. از زمان استارت دیوایس تا بوت شدن اندروید حدود ۲۰ ثانیه زمان لازم است که البته به سخت‌افزار شما بستگی دارد.

حالا می‌توان پروژه را روی این دیوایس Run یا Debug کرد. در نوار بالای دیوایس چند گزینه وجود دارد که کاربرد هرکدام مشخص است. یک گزینه‌ی ۳ نقطه هم وجود دارد که تنظیمات دستگاه مانند موقعیت مکانی، میکروفون، دوربین و سنسورها را در اختیار برنامه نویس قرار می‌دهد:

این آموزش هم به پایان رسید. موفق و پیروز باشید.

دانلود System Image ها

توجه داشته باشید دانلود این فایل‌ها تنها در صورتی لازم است که قصد نصب آفلاین سیستم ایمیج‌ها را داشته باشید.

تاریخ بروزرسانی فایل‌ها : ۱۴۰۱/۰۴/۲۵

» دانلود System Image Android 12 Google Play x86_64 (API 31) با حجم ۱٫۳ گیگابایت | لینک کمکی

» دانلود System Image Android 7 Google Play x86 (API 24) با حجم ۷۷۵ مگابایت | لینک کمکی

نوشته کار با امولاتور و ساخت دیوایس مجازی (AVD) اولین بار در اندروید استودیو پدیدار شد.

View Binding چیست؟

به نام خدا. View Binding یکی از امکانات زیر مجموعه‌ی Jetpack است که در کنفرانس IO گوگل در سال ۲۰۱۹ معرفی و در سال ۲۰۲۰ در Android Studio 3.6 و به عبارت دیگر Gradle 3.6 امکان فعالسازی و استفاده از آن مهیا شد. بنابراین استفاده از این قابلیت تنها از این نسخه و به بالا امکان پذیر است.
اولین مزیت View Binding این است که برای فعالسازی روی اندروید استودیو نیازی به افزودن (import) یک کتابخانه اضافی به پروژه اندرویدی نیست و درون پلاگین Gradle اندروید استودیو تعبیه شده است. بنابراین صرفا لازم است در فایل گریدلِ پروژه آنرا فعال کنیم.
همانطور که در ابتدای جلسه اشاره شد، View Binding جایگزینی برای تعریف view ها به شیوه سنتی آن یعنی استفاده از findViewById به شمار می‌رود.
اگر در حالت عادی در یک لایه XML تعداد ۱۰ عدد view (مانند Button، TextView، EditText و…) داشته باشیم برای هرکدام و به صورت جداگانه باید با استفاده از findViewById آنها را در Activity یا Fragment تعریف کنیم. چیزی شبیه به اکتیویتی زیر:

package ir.android_studio.testapp;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.widget.Button;
import android.widget.EditText;
import android.widget.TextView;

public class MainActivity extends AppCompatActivity {

    private Button sendBtn;
    private TextView textView;
    private EditText editText;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        sendBtn = findViewById(R.id.send_btn);
        textView = findViewById(R.id.txt_view);
        editText = findViewById(R.id.edit_text);

    }
}

علاوه بر نیاز به نوشتن و تکرار کدهای اضافی، ایرادات و باگ‌هایی این شیوه‌ی معرفی view ها دارد که با جایگزینی آن با View Binding این ایرادات مرتفع می‌گردد.
با استفاده از View Binding نیازی به تعریف view ها توسط برنامه نویس نبوده و فراخوانی view ها به صورت مستقیم توسط id (شناسه) آنها انجام می‌شود!

مقایسه View Binding در اندروید با سایر ابزارها و روش‌ها

برای تعریف view ها در اندروید چندین روش و کتابخانه وجود دارد که هرکدام مزایا و معایب مخصوص به خود را داشته و البته در نهایت به این نتیجه می‌رسیم که استفاده از View Binding در اندروید بهینه ترین روش فعلی خواهد بود.
در ادامه برای درک بهتر برتری View Binding نسبت به رقبا، به بررسی هرکدام می‌پردازیم:

findViewById

نیازی به معرفی نیست بنابراین به بررسی مزایا و معایب می‌پردازم:
عدم تاثیر در سرعت بیلد: شاید تنها مزیت آن را بتوان عدم تاثیر بر سرعت بیلد پروژه دانست چرا که هنگام اجرای برنامه کار می‌کند. اما این مزیت در برابر معایب متعدد آن اصلا قابل توجیه نیست.
کدهای اضافی: اولین امتیاز منفی این است که به ازاء هر view می‌بایست یک متغیر جداگانه ایجاد شود که طبیعتا حجم کدهای ما را افزایش خواهد داد.
Type safety نیست: واژه type به معنی “نوع” و safety به معنی “ایمنی” است. Type safety نبودن findViewById به این معنی است که در هنگام تعریف کردن یک view امکان بروز اشتباه در تعیین نوع آن وجود دارد.
برای مثال ممکن است view از جنس TextView باشد و ما اشتباها آن را در یک متغیر از جنس EditText تعریف کنیم.
Null safe نیست: اگر یک view موجود در layout فقط در شرایطی خاص در دسترس باشد ممکن است با یک خطای NullPointerException مواجه شویم. زیرا findViewById وضعیت نال بودن یا نبودن view را در شرایط مختلف بررسی نمی‌کند.
برای مثال حالتی را درنظر بگیرید که دو نسخه از activity_main.xml در پروژه داریم که یکی برای حالت عادی (صفحه عمودی یا portrait) و دیگری برای حالت افقی (landscape) استفاده می‌شود. چنانچه یک view در هردو layout مشترک نبوده و تنها در حالت portrait بکار رفته باشد هنگام قرار گرفتن دستگاه کاربر در حالت landscape می‌تواند سبب بروز خطای null شود.

کتابخانه ButterKnife

تا قبل از معرفی Data Binding توسط تیم اندروید، کتابخانه ButterKnife یکی از پرکاربردترین ابزار برای این منظور به شمار می‌رفت. البته کاربرد این کتابخانه محدود به bind (متصل) کردن view ها نمی‌شود و برای resource ها مانند رشته‌ها، رنگ‌ها و سایزها نیز کاربرد دارد. اما در این جلسه تنها قسمت مربوط به view ها مدنظر ماست.
کاهش حجم کدها: استفاده از این کتابخانه حجم کدها را نسبت به findViewById کاهش داده و به عبارتی کدهای تمیز تری می‌نویسیم. در این روش، به وسیله Annotation ها (حاشیه نویسی) می‌توان view های مدنظر را تعریف کرد. سه view ای که در قسمت قبل توسط findViewById تعریف شده بود را اینبار با استفاده از ButterKnife تعریف می‌کنم.
پس از اضافه کردن کتابخانه به پروژه، توسط annotation با نام @BindView هرکدام از view ها قابل تعریف است:

package ir.android_studio.testapp;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.widget.Button;
import android.widget.EditText;
import android.widget.TextView;

import butterknife.BindView;

public class MainActivity extends AppCompatActivity {

    @BindView(R.id.send_btn) Button sendBtn;
    @BindView(R.id.txt_view) TextView textView;
    @BindView(R.id.edit_text) EditText editText;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

    }
}

Type safety نیست: مانند findViewById کتابخانه ButterKnife هم type safety نیست و id هر نوع view ای را می‌توان به هر نوع View در کلاس جاوا متصل کرد. بنابراین ممکن است در هنگام اجرا با ارور Exception برخورد کنیم.
کاهش سرعت بیلد: از آنجایی که در حین کامپایل پروژه یک پردازشگر Annotation برای تولید (generate) کدها اجرا می‌شود در سرعت بیلد تاثیر منفی می‌گذارد. هرچند این کاهش سرعت بیلد چیزی نیست که ما را از استفاده یک کتابخانه منصرف کند زیرا به قول معروف مزایای آن بر معایبش می‌چربد. البته نه الان که View Binding را داریم!

Data Binding

تفاوت اساسی Data Binding با دو مورد قبل در این است که پس از فعالسازی این قابلیت در پروژه اندرویدی، به ازاء هر layout یا سایر resource ها به صورت خودکار یک کلاس ایجاد (generate) می‌شود. در این کلاس‌ها تمامی عناصر به صورت خودکار تعریف و مقدار دهی شده و به سادگی می‌توانیم در اکتیویتی یا فرگمنت به آنها دسترسی داشته باشیم.
کاهش حجم کدها: فعالسازی و استفاده از Data Binding نسبت به دو گزینه قبل نیاز به نوشتن کد کمتری دارد در نتیجه کدهای تمیزتری خواهیم داشت.
کاهش سرعت بیلد: در کلاس‌های ساخته شده توسط Data Binding از Annotation ها برای تعریف منابع استفاده می‌شود بنابراین مانند ButterKnife این مساله در کاهش سرعت build شدن پروژه تاثیرگذار خواهد بود.
Type safety و Null safe است: هردو مورد در Data Binding صدق می‌کند و از این بابت جای نگرانی نداریم.
در خصوص Data Binding بیشتر از این به بیان جزئیات نمی‌پردازم.

View Binding

رسیدیم به هدف! همانطور که در ابتدای مبحث گفته شد View Binding به نوعی زیر مجموعه‌ی Data Binding محسوب می‌شود که کاربرد آن در حذف findViewById خلاصه شده و به همین جهت علاوه بر ساده تر شدن فرآیند، نسبت به Data Binding خروجی بهینه‌تری را در اختیار ما قرار می‌دهد.
کاهش حجم کدها: با فعالسازی و استفاده از View Binding حجم کد مورد نیاز برای استفاده از view ها به حداقل ممکن می‌رسد و در بین این ۴ گزینه بالاترین امتیاز را به خود اختصاص داده است. تنها با نوشتن id هر view در اکتیویتی یا فرگمنت به view مربوطه دسترسی خواهیم داشت!
افزایش سرعت بیلد: شیوه کار View Binding هم مانند Data Binding است و با فعالسازی آن به ازاء هر layout یک کلاس ایجاد شده و تمامی view های آن درون کلاس به صورت خودکار تعریف می‌شود. اما در اینجا خبری از پردازش annotation ها نیست و در نتیجه سرعت بیلد به نسبت Data Binding بالاتر خواهد بود.
Type safety و Null safe است: این دو مورد را از پدر خودش یعنی Data Binding به ارث برده و با یکدیگر مشترک هستند.

حالا که گزینه‌های مختلف را بررسی کردیم و فهمیدیم بهترین گزینه در حال حاضر View Binding است در ادامه جلسه این قابلیت را در قالب یک پروژه بررسی و تمرین می‌کنیم.

ساخت پروژه View Binding و بررسی آن

ابتدا طبق مبحث آموزش ساخت پروژه در اندروید استودیو یک پروژه اندرویدی با نام ViewBinding می‌سازم. اکتیویتی را از نوع Empty Activity و زبان را Java انتخاب کردم.
در ابتدا و قبل از هرچیز لازم است قابلیت View Binding را در پروژه خود در اندروید استودیو فعال کنیم.

فعالسازی View Binding در اندروید استودیو

همانطور که قبلا اشاره شد این قابلیت به صورت پیش فرض در گریدل نسخه ۳٫۶ به بالا تعبیه شده و برای فعالسازی آن نیازی به اضافه کردن کتابخانه به پروژه نیست.
برای فعالسازی کافیست بلاک زیر را درون بلاک android در فایل build.gradle (project) اضافه و سپس پروژه را Sync کنم:

buildFeatures {
    viewBinding = true
}

viewBinding {
    enabled = true
}

پیاده سازی View Binding در اکتیویتی

همانطو که قبلا گفته شد، با فعالسازی View Binding به ازاء هر layout موجود در پروژه یک کلاس جداگانه ایجاد می‌شود. نام هر کلاس از نام layout مربوط به آن گرفته می‌شود که البته به صورت camel case نوشته شده و پسوند Binding هم به انتهای آن اضافه می‌شود.
برای مثال در این پروژه ما یک layout با نام activity_main.xml داریم. کلاسی که برای این layout ایجاد می‌شود ActivityMainBinding.java نام دارد. به عنوان یک مثال دیگر چنانچه در آینده یک layout با نام activity_map.xml به پروژه اضافه کنیم، کلاس ایجاد شده ActivityMapBinding.java نام خواهد داشت.
در این کلاس به ازاء هر view (ویجت) ای که در activity_main.xml وجود داشته و یک id به آن اختصاص داده شده باشد، یک متغیر ایجاد می‌شود و ما در اکتیویتی به آن دسترسی خواهیم داشت.
در layout پیش فرض پروژه یک View Group از جنس ConstraintLayout و یک TextView وجود دارد که البته برای TextView شناسه (id) به صورت پیش فرض تعریف نشده. بنابراین برای آنکه به این view دسترسی داشته باشم یک id به آن اختصاص می‌دهم:

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <TextView
      android:id="@+id/txt_view"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:text="Hello World!"
      app:layout_constraintBottom_toBottomOf="parent"
      app:layout_constraintLeft_toLeftOf="parent"
      app:layout_constraintRight_toRightOf="parent"
      app:layout_constraintTop_toTopOf="parent" />

  </androidx.constraintlayout.widget.ConstraintLayout>

در مرحله بعد لازم است یک آبجکت (شیء) از کلاس ActivityMainBinding داخل اکتیویتی تعریف کنیم تا به view ها به صورت مستقیم دسترسی داشته باشیم.

مشاهده می‌کنید کلاس ActivityMainBinding توسط اندروید استودیو شناسایی می‌شود. یعنی کلاس قبلا ساخته شده و قابل استفاده است.

MainActivity.java

package ir.android_studio.viewbinding;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;

import ir.android_studio.viewbinding.databinding.ActivityMainBinding;

public class MainActivity extends AppCompatActivity {

    private ActivityMainBinding mainBinding;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        mainBinding = ActivityMainBinding.inflate(getLayoutInflater());

        setContentView(R.layout.activity_main);


    }
}

نام دلخواه mainBinding را برای کلاس انتخاب کردم. سپس درون متد onCreate و قبل از setContentView توسط متد inflate آنرا مقداردهی کردم.
حالا به View Group اصلی layout و تمام view هایی که قبلا به layout اضافه شده و یا بعد از این اضافه شود دسترسی خواهیم داشت. البته مجدد تاکید می‌کنم view هایی که دارای ویژگی id باشند. بجز عنصر اصلی یا ریشه‌ی layout که نیازی به id نداشته و در متغیری با نام root ذخیره شده و توسط getRoot در دسترس است. در اینجا عنصر ریشه ما یک ConstraintLayout است که قبلا در جلسه آموزش کار با ConstraintLayout با آن آشنا شدیم.
ابتدا لازم است getRoot را به متد setContentView پاس بدهیم تا به اکتیویتی اعلام شود از طریق آبجکت Binding ای که ساخته‌ایم به layout دسترسی داشته باشد. getRoot را جایگزین R.layout.activity_main می‌کنم:

setContentView(mainBinding.getRoot());

حالا برای تست View Binding با استفاده از متد setText یک متن را روی txt_view چاپ می‌کنم:

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    mainBinding = ActivityMainBinding.inflate(getLayoutInflater());

    setContentView(mainBinding.getRoot());

    mainBinding.txtView.setText("تست ViewBinding");

}

پروژه را روی امولاتور (شبیه ساز) اندرویدی اجرا می‌کنم:

طبق تصویر فوق هم layout نمایش داده شد و هم متنی که در setText قرار داده بودیم.
برای تمرین و آشنایی بیشتر، یک Button به layout اضافه کرده و در اکتیویتی یک setOnClickListener برای آن تعریف می‌کنم. قبلا در آموزش کار با رویدادها در اندروید با این متد آشنا شده‌ایم. خط مربوط به setText را به درون رویداد مربوط به دکمه منتقل می‌کنم تا بعد از کلیک روی دکمه اجرا شود:

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <Button
        android:id="@+id/set_btn"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="80dp"
        android:text="جایگذاری متن"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

    <TextView
        android:id="@+id/txt_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Hello World!"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/set_btn" />

</androidx.constraintlayout.widget.ConstraintLayout>

MainActivity.java

package ir.android_studio.viewbinding;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;

import ir.android_studio.viewbinding.databinding.ActivityMainBinding;

public class MainActivity extends AppCompatActivity {

    private ActivityMainBinding mainBinding;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        mainBinding = ActivityMainBinding.inflate(getLayoutInflater());

        setContentView(mainBinding.getRoot());

        mainBinding.setBtn.setOnClickListener(view -> {

            mainBinding.txtView.setText("تست ViewBinding");

        });

    }
}

مجدد پروژه را اجرا کرده و روی دکمه جایگذاری متن کلیک می‌کنم:

دسترسی به کلاس‌های View Binding

اگر مایل بودید به محتوای کلاس‌های ساخته شده توسط View Binding دسترسی داشته باشید، بعد از بیلد شدن پروژه (یعنی هنگام اجرای پروژه روی دیوایس یا گزینه Rebuild Project در تب Build و یا گرفتن خروجی APK از پروژه) در مسیر زیر فایل کلاس‌ها در دسترس هستند:

برای نمایش محتوای دایرکتوری build لازم است نحوه نمایش پروژه در حالت Project و یا Project Files قرار گیرد. البته در پوشه‌ای که پروژه ذخیره شده هم می‌توان به فایل‌ها دسترسی داشت.

محتوای فعلی کلاس ActivityMainBinding.java پروژه من به اینصورت است:

ActivityMainBinding.java

// Generated by view binder compiler. Do not edit!
package ir.android_studio.viewbinding.databinding;

import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.Button;
import android.widget.TextView;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.constraintlayout.widget.ConstraintLayout;
import androidx.viewbinding.ViewBinding;
import ir.android_studio.viewbinding.R;
import java.lang.NullPointerException;
import java.lang.Override;
import java.lang.String;

public final class ActivityMainBinding implements ViewBinding {
  @NonNull
  private final ConstraintLayout rootView;

  @NonNull
  public final Button setBtn;

  @NonNull
  public final TextView txtView;

  private ActivityMainBinding(@NonNull ConstraintLayout rootView, @NonNull Button setBtn,
      @NonNull TextView txtView) {
    this.rootView = rootView;
    this.setBtn = setBtn;
    this.txtView = txtView;
  }

  @Override
  @NonNull
  public ConstraintLayout getRoot() {
    return rootView;
  }

  @NonNull
  public static ActivityMainBinding inflate(@NonNull LayoutInflater inflater) {
    return inflate(inflater, null, false);
  }

  @NonNull
  public static ActivityMainBinding inflate(@NonNull LayoutInflater inflater,
      @Nullable ViewGroup parent, boolean attachToParent) {
    View root = inflater.inflate(R.layout.activity_main, parent, false);
    if (attachToParent) {
      parent.addView(root);
    }
    return bind(root);
  }

  @NonNull
  public static ActivityMainBinding bind(@NonNull View rootView) {
    // The body of this method is generated in a way you would not otherwise write.
    // This is done to optimize the compiled bytecode for size and performance.
    int id;
    missingId: {
      id = R.id.set_btn;
      Button setBtn = rootView.findViewById(id);
      if (setBtn == null) {
        break missingId;
      }

      id = R.id.txt_view;
      TextView txtView = rootView.findViewById(id);
      if (txtView == null) {
        break missingId;
      }

      return new ActivityMainBinding((ConstraintLayout) rootView, setBtn, txtView);
    }
    String missingId = rootView.getResources().getResourceName(id);
    throw new NullPointerException("Missing required view with ID: ".concat(missingId));
  }
}

ملاحظه می‌کنید برای همه متغیرها انوتیشین @NonNull قید شده یعنی هیچکدام از آیتم‌ها تحت هیچ شرایطی نال نخواهند شد.
اما فرض کنید در پروژه خود یک activity_main.xml دیگر هم داشته باشیم که مربوط به طراحی صفحه در حالت Landscape (افقی) باشد و در این حالت یکی از view ها را حذف کرده باشیم. یا بلعکس یک view در این حالت اضافه کرده باشیم که قرار نیست در layout اصلی یعنی حالت عمودی وجود داشته باشد. در اینصورت بجای @NonNull انوتیشین @Nullable جایگزین خواهد شد که نشان می‌دهد این view می‌تواند در شرایطی نال باشد. بنابراین وضعیت نال مدیریت شده و به اصطلاح Null safe هستند.
به متد انتهای کلاس دقت کنید:

@NonNull
public static ActivityMainBinding bind(@NonNull View rootView) {
  // The body of this method is generated in a way you would not otherwise write.
  // This is done to optimize the compiled bytecode for size and performance.
  int id;
  missingId: {
    id = R.id.set_btn;
    Button setBtn = rootView.findViewById(id);
    if (setBtn == null) {
      break missingId;
    }

    id = R.id.txt_view;
    TextView txtView = rootView.findViewById(id);
    if (txtView == null) {
      break missingId;
    }

    return new ActivityMainBinding((ConstraintLayout) rootView, setBtn, txtView);
  }
  String missingId = rootView.getResources().getResourceName(id);
  throw new NullPointerException("Missing required view with ID: ".concat(missingId));
}

حدس می‌زنم انتظارش را نداشتید اینجا با findViewById مواجه شوید! اما واقعیت جز این نیست 🙂
View Binding از متد findViewById برای اتصال view ها به اکتیویتی استفاده می‌کند و انجام این مرحله تکراری و زجر آور را از روی دوش برنامه نویس برمی‌دارد. علاوه بر آن، در خصوص type و null هم ما را ایمن نگه می‌دارد.

View Binding و layout های include شده

اگر بخاطر داشته باشید در جلسه آموزش کار با Navigation Drawer با استفاده از تگ include یک layout را درون layout اصلی برنامه اضافه کردیم.
دسترسی به view های layout ای که در layout یک اکتیویتی include شده امکان پذیر است. یک layout جدید با نام layout_bottom.xml به پروژه اضافه کرده و یک TextView با شناسه btm_txt داخل آن تعریف می‌کنم:

layout_bottom.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <TextView
        android:id="@+id/btm_txt"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="متن پایینی"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />
    
</androidx.constraintlayout.widget.ConstraintLayout>

سپس layout را درون activity_main.xml توسط تگ include اضافه می‌کنم. دقت داشته باشید برای دسترسی به layout ضمیمه شده و view های درون آن توسط View Binding حتما برای تگ include هم باید یک id تعریف شود. من شناسه include_layout را انتخاب کردم:

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <Button
        android:id="@+id/set_btn"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="80dp"
        android:text="جایگذاری متن"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

    <TextView
        android:id="@+id/txt_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="252dp"
        android:text="Hello World!"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/set_btn" />

    <include
        layout="@layout/layout_bottom"
        android:id="@+id/include_layout"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/txt_view"
        app:layout_constraintVertical_bias="0.706"
        tools:layout_editor_absoluteX="-16dp" />

</androidx.constraintlayout.widget.ConstraintLayout>

حالا برای دسترسی به btm_txt در layout_bottom به اینصورت عمل می‌کنیم:

mainBinding.includeLayout.btmTxt

includeLayout همان شناسه include_layout است.
برای مثال متد setText را برای این TextView استفاده می‌کنم:

mainBinding.setBtn.setOnClickListener(view -> {

    mainBinding.txtView.setText("تست ViewBinding");
    mainBinding.includeLayout.btmTxt.setText("تعویض متن پایینی");

});

برای layout_bottom.xml هم یک کلاس ایجاد شده که LayoutBottomBinding.java نام دارد اما به دلیل اینکه در اینجا layout را درون یک layout دیگر include کرده‌ایم که قبلا یک آبجکت از آن در اکتیویتی ساخته شده، بدون نیاز به ساخت آبجکت جدید از layout زیرمجموعه، می‌توان به آن دسترسی داشت.

با اجرای پروژه و کلیک روی دکمه جایگذاری متن، متن این TextView هم تغییر می‌کند:

غیر فعال کردن View Binding برای یک لایه (layout) خاص

ممکن است در پروژه خود برای یک یا چند layout نیازی به ساخت کلاس View Binding نداشته باشیم. با توجه به اینکه افزایش تعداد کلاس‌ها در نهایت موجب کاهش سرعت بیلد و همچنین افزایش حجم پروژه می‌شود لذا می‌طلبد برای لایه‌هایی که به صورت ایستا (static) هستند و کاری با view های داخل آن نداریم، قابلیت View Binding را غیر فعال کنیم.
برای انجام این کار کافیست خط زیر به تگ layout ریشه آن اضافه شود:

tools:viewBindingIgnore="true"

برای مثال من یک لایه با نام layout_top.xml در پروژه ایجاد کرده‌ام و با توجه به ایستا بودن محتوای آن قصد دارم View Binding را روی این فایل غیر فعال کنم:

layout_top.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    xmlns:tools="http://schemas.android.com/tools"
    tools:viewBindingIgnore="true">

</androidx.constraintlayout.widget.ConstraintLayout>

واژه ignore به معنی “نادیده گرفتن” و “رد کردن” است بنابراین چنانچه برای این ویژگی مقدار true تعیین شود، قابلیت View Binding برای layout مدنظر نادیده گرفته خواهد شد.

پیاده سازی View Binding روی فرگمنت

قبلا در مبحث فرگمنت‌ها در اندروید با کاربرد Fragment آشنا شدیم. استفاده از View Binding در فرگمنت تفاوت زیادی با اکتیویتی ندارد.
یک فرگمنت با نام TestFragment به پروژه اضافه می‌کنم. سپس در layout فرگمنت یعنی fragment_text.xml یک TextView با شناسه fragment_txt تعریف می‌کنم:

fragment_test.xml

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".TestFragment">

    <!-- TODO: Update blank fragment layout -->
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="متن پیش فرض فرگمنت"
        android:id="@+id/fragment_txt"/>

</FrameLayout>

سپس در کلاس فرگمنت مانند آنچه قبلا در اکتیویتی انجام شد یک آبجکت از کلاسی که View Binding برای layout فرگنت ایجاد کرده می‌سازم:

TextFragment.java

package ir.android_studio.viewbinding;

import android.os.Bundle;
import androidx.fragment.app.Fragment;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;

import ir.android_studio.viewbinding.databinding.FragmentTestBinding;

public class TestFragment extends Fragment {

    private FragmentTestBinding frgBinding;

    @Override
    public View onCreateView(LayoutInflater inflater, ViewGroup container,
                             Bundle savedInstanceState) {

        //return inflater.inflate(R.layout.fragment_test, container, false);

        frgBinding = FragmentTestBinding.inflate(inflater, container, false);

        return frgBinding.getRoot();

    }

    @Override
    public void onDestroyView() {
        super.onDestroyView();

        frgBinding = null;

    }
}

مطابق کد فوق ابتدا از کلاس FragmentTestBinding یک نمونه با نام frgBinding ساخته‌ام. سپس inflate اصلی فرگمنت را حذف (کامنت) کرده و inflate مربوط به View Binding را مانند اکتیویتی و البته اندکی تفاوت بجای آن تعریف کرده‌ام. در خط بعد هم متد getRoot برگردانده یا return شد.
همچنین متد onDestroyView که مربوط به چرخه حیات فرگمنت هست را اضافه و درون آن آبجکت ساخته شده از View Binding را null می‌کنم تا هنگام حذف فرگمنت از اکتیویتی، این آبجکت نال شود.
یک متد setText برای TextView فرگمنت در onCreateView و قبل از دستور return تعریف می‌کنم:

public View onCreateView(LayoutInflater inflater, ViewGroup container,
                         Bundle savedInstanceState) {
    
    //return inflater.inflate(R.layout.fragment_test, container, false);

    frgBinding = FragmentTestBinding.inflate(inflater, container, false);

    frgBinding.fragmentTxt.setText("متن جدید فرگمنت");

    return frgBinding.getRoot();

}

در نهایت، فرگمنت را در activity_main.xml تعریف می‌کنم. از اختصاص id به تگ fragment فراموش نکنید!

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <Button
        android:id="@+id/set_btn"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="80dp"
        android:text="جایگذاری متن"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

    <TextView
        android:id="@+id/txt_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="252dp"
        android:text="Hello World!"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/set_btn" />

    <include
        android:id="@+id/include_layout"
        layout="@layout/layout_bottom"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:layout_constraintTop_toBottomOf="@+id/txt_view"
        tools:layout_editor_absoluteX="-16dp" />

    <fragment
        android:id="@+id/fragment_one"
        android:name="ir.android_studio.viewbinding.TestFragment"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/include_layout" />

</androidx.constraintlayout.widget.ConstraintLayout>

با اجرای مجدد پروژه می‌بینیم که متن موجود در setText روی TextView جایگزین متن پیش فرض آن شده:

این جلسه هم به پایان رسید.
موفق و پیروز باشید.

مطالعه‌ی بیشتر:

https://developer.android.com/topic/libraries/view-binding
https://developer.android.com/topic/libraries/data-binding

توجه : سورس پروژه درون پوشه Exercises قرار دارد

نوشته خداحافظ findViewById؛ سلام View Binding اولین بار در اندروید استودیو پدیدار شد.

نحوه‌ دریافت پیامک در اپلیکیشن اندرویدی

به نام خدا. به طور کل با استفاده از دو کلاس SmsMessage و Cursor می‌توانیم به پیامک‌های موجود در دستگاه اندرویدی دسترسی داشته باشیم. البته روش متداول، استفاده از SmsMessage است. در ادامه به بررسی هر دو روش پرداخته و سپس به صورت عملی پیاده سازی می‌کنیم.
SmsMessage: کلاسی با نام SmsMessage در API 4 به سیستم عامل اندروید اضافه شده که وظیفه دسترسی به پیامک یا همان SMS را در دستگاه‌های اندرویدی بر عهده دارد.
البته از API 1 هم کلاسی با این نام وجود داشت (android.telephony.gsm.SmsMessage) که تنها از پروتکل GSM پشتیبانی می‌کرد. اما در API 4 این کلاس با android.telephony.SmsMessage جایگزین شد که از هر دو پروتکل GSM و CDMA پشتیبانی می‌کند.
همچنین برای شنود رویداد مربوط به دریافت پیامک لازم است از برودکست رسیور استفاده کنیم که قبلا در آموزش BroadcastReceiver در اندروید با این مبحث آشنا شدیم.
Cursor: علاوه بر کلاس SmsMessage با استفاده از کلاس Cursor هم می‌توان به آرشیو پیامک‌ها دسترسی داشت که با وجود کلاس SmsMessage استفاده از آن جایگاهی نخواهد داشت با این حال در انتهای آموزش به این مورد نیز اشاره مختصری خواهیم کرد.

ساخت پروژه دریافت SMS در اندروید استودیو

برای بررسی نحوه دریافت پیامک (SMS) در برنامه نویسی اندروید مطابق مبحث آموزش ساخت پروژه در اندروید استودیو یک پروژه اندرویدی با نام ReceiveSMS می‌سازم. اکتیویتی را از نوع Empty Activity و زبان را Java انتخاب کردم.

دریافت پیامک (SMS) توسط SmsMessage

اگر بخاطر داشته باشید در جلسه نحوه ارسال پیامک (SMS) در برنامه نویسی اندروید در مانیفست پروژه مجوز ارسال پیامک را تعریف کردیم. در این پروژه لازم است عکس آن یعنی مجوز دریافت SMS را تعریف کنیم:

<uses-permission android:name="android.permission.RECEIVE_SMS" />

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="ir.android_studio.receivesms">

    <uses-permission android:name="android.permission.RECEIVE_SMS" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.ReceiveSMS">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

در قدم بعد لازم است یک BroadcastReceiver ایجاد کنم. بر خلاف پروژه ارسال SMS که برودکست درون اکتیویتی و به صورت داینامیک رجیستر شد، در این جلسه برودکست را در کلاس مجزا تعریف کرده و همچنین رجیستر یا ثبت آن را به صورت استاتیک و درون Manifest انجام می‌دهم.
یک کلاس با نام SMSBroadcastReceiver به پروژه اضافه کرده و آنرا از BroadcastReceiver مشتق می‌کنم. سپس متد onReceive را اضافه می‌کنم:

SMSBroadcastReceiver.java

package ir.android_studio.receivesms;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

public class SMSBroadcastReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        
    }
}

سپس برودکست رسیور را در مانیفست پروژه ثبت می‌کنم:

<receiver android:name=".SMSBroadcastReceiver">
    <intent-filter>
        <action android:name="android.provider.Telephony.SMS_RECEIVED" />
    </intent-filter>
</receiver>

کد کامل مانیفست:
AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="ir.android_studio.receivesms">

    <uses-permission android:name="android.permission.RECEIVE_SMS" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.ReceiveSMS">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <receiver android:name=".SMSBroadcastReceiver">
            <intent-filter>
                <action android:name="android.provider.Telephony.SMS_RECEIVED" />
            </intent-filter>
        </receiver>
    </application>

</manifest>

یک اکشن با نام android.provider.Telephony.SMS_RECEIVED در مانیفست تعریف کردیم. این اکشن وظیفه بررسی رویدادهای مربوط به دریافت پیامک را در سیستم عامل بر عهده دارد.
قبل از پیاده سازی کلاس SmsMessage قصد دارم صرفا عملکرد برودکست را بررسی کنم و مطمئن شوم action ای که در مانیفست تعریف کردم می‌تواند به دریافت پیامک واکنش نشان دهد. بنابراین در متد onReceive برودکست رسیور صرفا یک پیغام Toast تعریف می‌کنم:

public void onReceive(Context context, Intent intent) {

    Toast.makeText(context, "یک پیامک دریافت شد", Toast.LENGTH_SHORT).show();

}

با توجه به اینکه قصد دارم پروژه را روی یک دیوایس بالاتر از اندروید ۶ اجرا کنم، لازم است کدهای مربوط به Runtime Permission را مطابق آموزش Runtime Permission در اندروید به اکتیویتی اضافه کنم:

MainActivity.java

package ir.android_studio.receivesms;

import androidx.annotation.NonNull;
import androidx.appcompat.app.AlertDialog;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import android.Manifest;
import android.content.DialogInterface;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.widget.Toast;

public class MainActivity extends AppCompatActivity {

    private final int SMS_REQUEST_CODE = 100;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        if (ContextCompat.checkSelfPermission(MainActivity.this, Manifest.permission.RECEIVE_SMS) != PackageManager.PERMISSION_GRANTED) {

            requestReceiveSMSpermission();

        } else {

            Toast.makeText(this, "مجوز قبلا دریافت شده", Toast.LENGTH_SHORT).show();

        }

    }

    private void requestReceiveSMSpermission() {

        if (ActivityCompat.shouldShowRequestPermissionRationale(MainActivity.this, Manifest.permission.RECEIVE_SMS)) {

            new AlertDialog.Builder(this)
                    .setTitle("درخواست مجوز")
                    .setMessage("برای عملکرد صحیح برنامه باید دسترسی به دریافت پیامکتایید شود")
                    .setPositiveButton("موافقم", new DialogInterface.OnClickListener() {
                        @Override
                        public void onClick(DialogInterface dialogInterface, int i) {

                            reqPermission();

                        }
                    })
                    .setNegativeButton("لغو", new DialogInterface.OnClickListener() {
                        @Override
                        public void onClick(DialogInterface dialogInterface, int i) {

                            dialogInterface.dismiss();

                        }
                    })
                    .create()
                    .show();

        } else {

            reqPermission();

        }

    }

    private void reqPermission() {

        ActivityCompat.requestPermissions(MainActivity.this, new String[] {Manifest.permission.RECEIVE_SMS}, SMS_REQUEST_CODE);

    }

    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {

        super.onRequestPermissionsResult(requestCode, permissions, grantResults);

        if (requestCode == SMS_REQUEST_CODE) {

            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {

                Toast.makeText(this, "مجوز تایید شد", Toast.LENGTH_SHORT).show();

            } else {

                Toast.makeText(this, "مجوز رد شد", Toast.LENGTH_SHORT).show();

            }

        }

    }

}

یکی از دیوایس‌های امولاتور اندرویدی Genymotion را اجرا می‌کنم. یکی از امکانات کاربردی شبیه سازهای اندرویدی از جمله Genymotion و همچنین AVD (شبیه ساز داخلی اندروید استودیو) قابلیت ارسال پیامک به دستگاه و همچنین برقراری تماس است. بدون آنکه نیاز به اجرا و تست برنامه روی یک دستگاه واقعی داشته باشیم.
پروژه را روی شبیه ساز اجرا کرده و مجوز دسترسی به پیامک‌ها را برای برنامه تایید می‌کنم. سپس روی آیکون Phone منوی سمت راست دیوایس کلیک می‌کنم:

در کادر Phone یک شماره فرستنده و متن دلخواه وارد کرده و پیام را ارسال می‌کنم. بلافاصله پیغام Toast ای که در متد onReceive تعریف کرده بودم اجرا شد:

تا اینجای کار مطمئن شدیم برنامه ما می‌تواند به درستی رویدادهای مربوط به دریافت پیامک را شنود کند. در قدم بعد می‌خواهیم محتوای SMS دریافتی را به دست بیاوریم که شامل شماره ارسال کننده پیام و همچنین متن پیامک می‌باشد.
پیغام Toast داخل متد onReceive برودکست رسیور را حذف کرده و کد زیر را جایگزین آن می‌کنم:

if (intent.getAction().equals("android.provider.Telephony.SMS_RECEIVED")) {

    Bundle mBundle = intent.getExtras();
    SmsMessage[] msg;
    String smsFrom;

    if (mBundle != null) {
        try {
            Object[] mPdus = (Object[]) mBundle.get("pdus");
            msg = new SmsMessage[mPdus.length];

            for (int i = 0; i < mPdus.length; i++) {
                msg[i] = SmsMessage.createFromPdu((byte[]) mPdus[i]);
                smsFrom = msg[i].getOriginatingAddress();
                String smsBody = msg[i].getMessageBody();

                Toast.makeText(context, "شماره: " + smsFrom + " / پیام: " + smsBody, Toast.LENGTH_SHORT).show();
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

در ابتدا یک if تعریف شده که بررسی می‌کند کدها تنها در صورتی اجرا شوند که اینتنت اکشن دریافتی از نوع android.provider.Telephony.SMS_RECEIVED باشد. یعنی دقیقا همان اکشنی که قبلا در AndroidManifest.xml و در تگ receiver ثبت کردیم.
سپس یک نمونه از Bundle و SmsMessage و یک String ساخته شده. در ادامه ابتدا بررسی می‌شود آیا مقدار ذخیره شده در mBundle نال است یا نه؛ یعنی داده‌ای که مربوط به محتوای یک پیامک باشد در باندل ذخیره شده یا خیر.
یک نمونه از Object[] با نام دلخواه mPdus ایجاد شده که داده‌ها با فرمت PDU (مخفف Protocol Data Unit) در آن ذخیره می‌شود. با استفاده از PDU به ساختار محتوای پیام دریافتی دسترسی داریم.
سپس در حلقه for با استفاده از SmsMessage.createFromPdu() محتوای پیام دریافتی تفکیک می‌شود. همانطور که ملاحظه می‌کنید در دو خط بعد توسط getOriginatingAddress و getMessageBody به ترتیب به شماره ارسال کننده پیام و متن پیام دسترسی خواهیم داشت. کاربرد متدها از نحوه نامگذاری آنها هم مشخص است. عبارت Originating Address به معنی آدرس مبدا و Message Body به معنی بدنه یا متن پیام است.
در انتها، این دو آیتم در یک پیغام Toast قرار داده شده است.
کد کامل کلاس برودکست رسیور:

SMSBroadcastReceiver.java

package ir.android_studio.receivesms;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.os.Bundle;
import android.telephony.SmsMessage;
import android.widget.Toast;

public class SMSBroadcastReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {

        // Toast.makeText(context, "یک پیامک دریافت شد", Toast.LENGTH_SHORT).show();

        if (intent.getAction().equals("android.provider.Telephony.SMS_RECEIVED")) {

            Bundle mBundle = intent.getExtras();
            SmsMessage[] msg;
            String smsFrom;

            if (mBundle != null) {
                try {
                    Object[] mPdus = (Object[]) mBundle.get("pdus");
                    msg = new SmsMessage[mPdus.length];

                    for (int i = 0; i < mPdus.length; i++) {
                        msg[i] = SmsMessage.createFromPdu((byte[]) mPdus[i]);
                        smsFrom = msg[i].getOriginatingAddress();
                        String smsBody = msg[i].getMessageBody();

                        Toast.makeText(context, "شماره: " + smsFrom + " / پیام: " + smsBody, Toast.LENGTH_SHORT).show();
                    }
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }

        }

    }
}

پروژه را دوباره اجرا کرده و با استفاده از گزینه Phone یک پیام جدید ارسال می‌کنم. حالا شماره ارسال کننده و متن SMS هم در Toast نمایش داده می‌شود:

دریافت پیامک (SMS) توسط Cursor

همانطور که در ابتدای جلسه اشاره شد، با وجود کلاس SmsMessage استفاده از Cursor برای دریافت پیامک توجیهی نخواهد داشت اما لازم دانستم حداقل برای تمرین به این مورد هم اشاره کنم.
یک پروژه جدید بسازید و TextView پیش فرض اکتیویتی را به Button تبدیل کنید. سپس کد زیر را در رویداد onClickListener دکمه قرار دهید (از تعریف Runtime Permission فراموش نکنید).

Cursor cursor = getContentResolver().query(Uri.parse("content://sms"), null, null, null, null);

cursor.moveToFirst();

Toast.makeText(this, cursor.getString(12), Toast.LENGTH_SHORT).show();

بعد از اجرای پروژه و تایید مجوز دریافت SMS، مانند قبل یک پیامک ارسال کرده و سپس روی Button کلیک کنید. متن پیامک در قالب Toast نمایش داده خواهد شد. البته در این روش هم می‌توان شماره ارسال کننده پیامک را دریافت کرد که به آن نمی‌پردازم.

توجه : سورس پروژه درون پوشه Exercises قرار دارد

نوشته دریافت پیامک (SMS) در برنامه اندرویدی + سورس پروژه اولین بار در اندروید استودیو پدیدار شد.

کاربردهای ارسال پیامک از طریق اپلیکیشن

به نام خدا. ارسال پیامک از طریق برنامه‌های اندرویدی کاربردهای متفاوتی می‌تواند داشته باشد. برای مثال در برخی از همراه بانک‌ها کاربر امکان انتخاب اینترنت یا پیامک (SMS) را به عنوان بستر ارسال و دریافت اطلاعات در اختیار دارد.
همچنین یکی دیگر از کاربردهای ارسال پیامک (SMS) در برنامه نویسی اندروید ارسال موقعیت جغرافیایی فرد (بر اساس مختصات GPS) به یک شماره خاص است. قابلیتی که به فرد این امکان را می‌دهد تا در شرایط اضطراری، با لمس یک دکمه موقعیت جغرافیایی خود را برای شماره موبایلی که قبلا در برنامه تعریف کرده ارسال کند. یا برنامه‌ای که بر روی دستگاه اندرویدی کودکان نصب می‌شود تا در فاصله‌های زمانی معین، مختصات جغرافیایی او را به صورت خودکار به شماره همراه والدینش ارسال می‌کند.
ارسال پیامک به مرکز سرویس دهنده‌ی اپلیکیشن به جهت تائید شماره همراه کاربر در هنگام عضویت یکی دیگر از کاربردهای این قابلیت است.
قابلیت ارسال پیامک از اپلیکیشن کاربردهای متعدد دیگری می‌تواند داشته باشد که استفاده از آن به ماهیت برنامه بستگی دارد.

نحوه ارسال پیامک در اندروید

ارسال پیامک (SMS) در برنامه نویسی اندروید به دو طریق امکان پذیر است. روش نخست استفاده از intent است که در صورت پیاده سازی این روش در برنامه، کاربر برای ارسال پیامک به برنامه مدیریت پیامک پیش فرض دستگاه خود منتقل خواهد شد.
اما در روش دوم با استفاده از کلاس SmsManager فرایند ارسال پیامک درون خود برنامه و در پشت صحنه انجام شده و کاربر از جابجایی بین برنامه اصلی و برنامه مدیریت SMS خود بی نیاز خواهد بود. علاوه بر آن دسترسی به محتوای پیامک و امکان ویرایش آن نیز مقدور نیست.
در ادامه جلسه به بررسی هردو روش می‌پردازیم.

ارسال پیامک (SMS) از طریق Intent

قبلا در جلسه آموزش کار با intent در اندروید با کاربرد اینتنت‌ها در برنامه نویسی اندروید آشنا شدیم. ضمن اینکه در همان جلسه یکی از مثال‌های کاربرد intent به قابلیت ارسال پیامک از طریق برنامه مدیریت SMS پیش فرض دستگاه اختصاص یافته بود که توضیحات کامل را می‌توانید مطالعه کنید. بنابراین از پرداختن مجدد به توضیحات این روش اجتناب می‌کنم و صرفا جهت یاداوری، کد اینتنت مربوط به ارسال پیامک از طریق برنامه مدیریت پیامک را در اینجا ذکر می‌کنم:

public void contactMessage(View v) {
    Intent cnt_msg = new Intent();
    cnt_msg.setAction(Intent.ACTION_VIEW);
    cnt_msg.setData(Uri.parse("sms:+989158888888"));
    cnt_msg.putExtra("sms_body", "سلام. در خصوص اپلیکیشن شرکتتون یه پیشنهاد داشتم");
    startActivity(cnt_msg);
}

با اجرای تابع فوق، کاربر به برنامه پیامک پیش فرض دیوایس اندرویدی منتقل شده و شماره‌ی گیرنده پیام و همچنین متن پیامک به صورت خودکار اضافه می‌شود:

در اینجا کاربر در صورت تمایل قبل از ارسال پیامک می‌تواند محتوای پیام را ویرایش کند.
اما این شیوه ارسال پیامک به دلیل طولانی بودن فرایند ارسال و همچنین دسترسی کاربر به محتوای آن کاربرد چندانی نداشته و برنامه نویسان اندرویدی عموما روش دوم را بکار می‌گیرند که در ادامه مبحث معرفی می‌کنم.

ارسال پیامک (SMS) از طریق کلاس SmsManager

بر خلاف روش قبل یعنی ارسال پیامک از طریق intent در این روش و با استفاده از کلاس SmsManager پیامک به طور مستقیم و درون خود برنامه به مقصد ارسال شده و کاربر دسترسی به محتوای پیامک نخواهد داشت. به عبارت دیگر، کاربر از فرایند ارسال پیامک آگاه نخواهد شد.
با استفاده از SmsManager می‌توان ۴ نوع پیام را ارسال کرد که لازم است کاربرد هرکدام را توضیح دهم:
sendTextMessage: همانطور که از نام این متد پیداست، برای ارسال پیامک (SMS) معمولی بکار می‌رود. یعنی ارسال پیامک متنی در قالب یک پیام و به مقصد از قبل تعیین شده. درست همان چیزی که در این جلسه نیاز داریم.
sendMultipartTextMessage: عملیات مشابه متد قبل را انجام می‌دهد با این تفاوت که می‌توان پیام را در قالب چند پیام جداگانه به مقصد ارسال کرد.
sendDataMessage: از این متد برای ارسال پیام داده محور و در یک پورت مشخص استفاده می‌شود.
sendMultimediaMessage: چنانچه قصد ارسال پیام مولتی مدیا یا همان MMS (مانند ارسال عکس) داشته باشیم باید از این متد استفاده کنیم.

همانطور که در توضیحات قبل اشاره شد، در این جلسه می‌خواهیم یک پیامک متنی ساده و تک قسمتی را ارسال کنیم که متد sendTextMessage مناسب این کار است. با ادامه جلسه همراه باشید.

ساخت پروژه اندرویدی ارسال پیامک

مطابق مبحث آموزش ساخت پروژه در اندروید استودیو یک پروژه اندرویدی با نام SendSMS می‌سازم. اکتیویتی را از نوع Empty Activity و زبان را Java انتخاب کردم.
در این پروژه قصد داریم با استفاده از کلاس SmsManager بصورت درون برنامه‌ای و بدون نیاز به برنامه مدیریت پیامک، یک پیام کوتاه به مقصدی مشخص ارسال کنیم. همچنین نحوه فعالسازی گزارش ارسال (sent) و گزارش تحویل (delivery) پیامک و در دسترس بودن یا نبودن سیم کارت جهت ارسال SMS را نیز بررسی خواهیم کرد.
در رابط کاربری این پروژه تنها به یک دکمه برای ارسال متن پیامک از پیش تعیین شده نیاز داریم. بنابراین در layout پیش فرض اکتیویتی پروژه کافیست TextView موجود در مرکز ویو گروپ ConstraintLayout را به Button تبدیل کرده و یک id به آن اختصاص دهم:

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <Button
        android:id="@+id/sms_btn"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="ارسال پیامک"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

اگر با این layout آشنایی ندارید آموزش کار با ConstraintLayout را مطالعه کنید. حالا رویداد مربوط به دکمه را در اکتیویتی تعریف می‌کنم:

MainActivity.java

package ir.android_studio.sendsms;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.widget.Button;

public class MainActivity extends AppCompatActivity {

    Button sendBtn;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        sendBtn = findViewById(R.id.sms_btn);

        sendBtn.setOnClickListener(view -> {

        });

    }
}

نکته: در نسخه‌های اخیر اندروید استودیو، هنگام اضافه کردن متد setOnClickListener پیشنهادی مبنی بر جایگزینی View.OnClickListener با lambda داده می‌شود که با زدن alt+Enter یا کلیک روی آیکون لامپ، جایگزینی انجام می‌شود. تفاوت در کوتاه شدن کدهاست.

پس از تبدیل، کد رویداد دکمه به اینصورت تبدیل می‌شود:

sendBtn.setOnClickListener(view -> {

});

تعریف مجوز ارسال پیامک

در قدم اول لازم است مجوز یا Permission ارسال پیامک (SMS) را در برنامه تعریف کنیم. ابتدا پرمیشن SEND_SMS را در مانیفست پروژه تعریف می‌کنم:

<uses-permission android:name="android.permission.SEND_SMS"/>

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="ir.android_studio.sendsms">

    <uses-permission android:name="android.permission.SEND_SMS"/>

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.SendSMS">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

همچنین مطابق جلسه آموزش پیاده سازی Runtime Permission برای دریافت مجوز در دستگاه‌های اندرویدی ۶ و به بالا کدهای لازم را به پروژه اضافه می‌کنم:

MainActivity.java

package ir.android_studio.sendsms;

import androidx.annotation.NonNull;
import androidx.appcompat.app.AlertDialog;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import android.Manifest;
import android.content.DialogInterface;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.widget.Button;
import android.widget.Toast;

public class MainActivity extends AppCompatActivity {

    Button sendBtn;
    private final int SMS_REQUEST_CODE = 100;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        sendBtn = findViewById(R.id.sms_btn);

        sendBtn.setOnClickListener(view -> {

            if (ContextCompat.checkSelfPermission(MainActivity.this, Manifest.permission.SEND_SMS) != PackageManager.PERMISSION_GRANTED) {
                
                requestSendSMSpermission();
                
            } else {
                
                sendMessage();
                
            }

        });

    }

    private void requestSendSMSpermission() {

        if (ActivityCompat.shouldShowRequestPermissionRationale(MainActivity.this, Manifest.permission.SEND_SMS)) {

            new AlertDialog.Builder(this)
                    .setTitle("درخواست مجوز")
                    .setMessage("برای عملکرد صحیح برنامه باید دسترسی به ارسال پیامک تایید شود")
                    .setPositiveButton("موافقم", new DialogInterface.OnClickListener() {
                        @Override
                        public void onClick(DialogInterface dialogInterface, int i) {

                            reqPermission();

                        }
                    })
                    .setNegativeButton("لغو", new DialogInterface.OnClickListener() {
                        @Override
                        public void onClick(DialogInterface dialogInterface, int i) {

                            dialogInterface.dismiss();

                        }
                    })
                    .create()
                    .show();

        } else {

            reqPermission();

        }

    }

    private void reqPermission() {

        ActivityCompat.requestPermissions(MainActivity.this, new String[] {Manifest.permission.SEND_SMS}, SMS_REQUEST_CODE);

    }

    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {

        if (requestCode == SMS_REQUEST_CODE) {

            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                
                sendMessage();
                
            } else {
                
                Toast.makeText(this, "مجوز رد شد", Toast.LENGTH_SHORT).show();
                
            }

        }

    }
    
}

پیاده سازی کلاس SmsManager

با اضافه شدن کدهای فوق، پس از لمس دکمه “ارسال پیامک” چنانچه کاربر مجوز ارسال SMS را به برنامه اعطا کند، تابع sendMessage فراخوانی خواهد شد. تابعی با همین نام درون اکتیویتی و بعد از متد onCreate اضافه کرده و کدهای مربوط به ارسال پیامک را درون آن می‌نویسم:

private void sendMessage() {

    try {
        
        SmsManager smsManager = SmsManager.getDefault();
        smsManager.sendTextMessage("+989158888888", null, "تست ارسال پیامک", null, null);

        Toast.makeText(MainActivity.this, " پیامک ارسال شد", Toast.LENGTH_SHORT).show();
        
    } catch (Exception e) {
        
        Toast.makeText(MainActivity.this, " پیامک ارسال نشد", Toast.LENGTH_SHORT).show();
        
    }

}

کدهای مربوط به ارسال پیامک را درون یک try catch قرار داده‌ام تا چنانچه به هر دلیلی فرایند ارسال SMS انجام نشد، برنامه کرش نکند.
در کد فوق ابتدا یک نمونه (شیء) از کلاس SmsManager با نام دلخواه smsManager ایجاد شده که برای مقدار دهی آن، متد getDefault فراخوانی شده است. این متد شناسه سیم کارت پیش فرض دستگاه اندرویدی را دریافت می‌کند که برای ارسال پیامک ضروری است. توصیه می‌کنم توضیحات تکمیلی اینجا و اینجا را در خصوص دستگاه‌های دو سیم کارت مطالعه کنید.
در خط دوم، متد sendTextMessage تعریف شده که ۴ پارامتر ورودی می‌پذیرد. در تصویر زیر جنس هر ورودی قابل تشخیص است:

destinationAddress: پارامتر نخست از جنس String بوده که همان شماره گیرنده پیام می‌باشد.
scAddress: پارامتر دوم مربوط به آدرس یا شماره‌ی Service Center پیامک اپراتوری است که کاربر از سیم کارت آن استفاده می‌کند. به طور معمول این شماره توسط کلاینت تعیین نمی‌شود و به عهده‌ی خود اپراتور است. بنابراین مقدار null را وارد می‌کنیم.
text: واضح است که این پارامتر، محتوای پیام را شامل می‌شود.
sentIntent و deliveryIntent: به ترتیب برای دریافت گزارش ارسال و گزارش تحویل پیامک استفاده می‌شود که در این مرحله به جهت درک بهتر عملکرد اصلی کلاس، برای هردو مقدار null درنظر گرفتم. بنابراین در این مرحله به نتیجه‌ی ارسال و یا تحویل پیامک به مقصد دسترسی نخواهیم داشت.
نگران نباشید! به این دو مورد هم در ادامه جلسه می‌پردازیم.
در همین مرحله پروژه را اجرا می‌کنم تا عملکرد کلاس SmsManager را بررسی کنیم.

با توجه به اینکه یک دیوایس با Android 10 را روی شبیه ساز (امولاتور) اندرویدی اجرا کرده‌ام، با کلیک روی دکمه ارسال پیامک ابتدا باید مجوز ارسال پیامک را تایید کنم.
با تایید مجوز، پیغام “پیامک ارسال شد” روی صفحه ظاهر شد که نشان می‌دهد عملکرد برنامه تا اینجای کار درست بوده:

پیامک ارسال شده در برنامه مدیریت SMS پیش فرض دستگاه نیز قابل مشاهده است:

دریافت گزارش ارسال و گزارش تحویل پیامک

در قسمت قبل صرفا یک SMS توسط کلاس SmsManager ارسال کردیم و دسترسی به گزارش ارسال و تحویل پیامک نداشتیم و برای هردو پارامتر sentIntent و deliveryIntent مقدار null داده بودیم.
اما در این قسمت و در ادامه‌ی آموزش ارسال پیامک (SMS) در برنامه نویسی اندروید با استفاده از BroadcastReceiver و PendingIntent رویدادهای مربوط به وضعیت ارسال و تحویل پیامک را شنود کرده و پیغام مربوط آن را چاپ می‌کنیم.
ابتدا در بدنه اصلی کلاس اکتیویتی دو متغیر از جنس String با نام و مقدار دلخواه تعریف می‌کنم. از این دو متغیر برای برقراری ارتباط بین BroadcastReceiver و PendingIntent مربوط به یکدیگر استفاده خواهیم کرد:

String SMS_SENT = "SMS_SENT";
String SMS_DELIVERED = "SMS_DELIVERED";

سپس مطابق جلسه آموزش شنود رویدادها در اندروید توسط BroadcastReceiver دو برودکست را درون متد sendMessage داخل بلاک try و قبل از smsManager، رجیستر می‌کنم:

//Broadcast for Sent SMS
registerReceiver(new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {

        String state = "";
        switch (getResultCode()) {
            case Activity.RESULT_OK:
                state = "پیامک ارسال شد";
                break;
            case SmsManager.RESULT_ERROR_GENERIC_FAILURE:
                state = "یک خطای عمومی رخ داد";
                break;
            case SmsManager.RESULT_ERROR_NO_SERVICE:
                state = "اپراتور در دسترس نیست";
                break;
            case SmsManager.RESULT_ERROR_NULL_PDU:
                state = " پروتکل PDU در دسترس نیست";
                break;
            case SmsManager.RESULT_ERROR_RADIO_OFF:
                state = "سیم کارت در دسترس نیست";
                break;
        }
        Toast.makeText(context, state, Toast.LENGTH_SHORT).show();
    }
}, new IntentFilter(SMS_SENT));

//Broadcast for Delivered SMS
registerReceiver(new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        String state = "";
        switch (getResultCode()) {
            case Activity.RESULT_OK:
                state = "پیامک تحویل داده شد";
                break;
            case Activity.RESULT_CANCELED:
                state = "پیامک تحویل داده نشد";
                break;
        }
        Toast.makeText(context, state, Toast.LENGTH_SHORT).show();
    }
}, new IntentFilter(SMS_DELIVERED));

برودکست اول برای شنود وضعیت ارسال پیامک استفاده خواهد شد. چنانچه پیامک با موفقیت به سرویس دهنده (اپراتور) ارسال شود، پیغام “پیامک ارسال شد” و در غیر اینصورت سایر پیغام‌های مناسب وضعیت رخ داده نمایش داده خواهد شد.
برای حالت عدم ارسال پیامک، ۴ حالت مختلف تعریف شده که با توجه به وضعیت دریافتی از SmsManager، نوع خطا را به کاربر اعلام می‌کند. خطای دریافتی می‌تواند یک خطای عمومی بوده یا مربوط به در دسترس نبودن اپراتور، در دسترس نبودن سیم کارت و یا پروتکل PDU (Protocol Data Unit) باشد.
برودکست دوم نیز برای شنود وضعیت تحویل یا عدم تحویل SMS به گیرنده بکار می‌رود.
بعد از برودکست‌ها دو PendingIntent به صورت زیر تعریف می‌کنم:

PendingIntent sentSMS = PendingIntent.getBroadcast(this, 0, new Intent(SMS_SENT), 0);
PendingIntent deliverSMS = PendingIntent.getBroadcast(this, 0, new Intent(SMS_DELIVERED), 0);

قبلا در جلسه آموزش ساخت نوتیفیکیشن‌های حرفه‌ای در اندروید با کاربرد PendingIntent ها آشنا شدیم. با استفاده از متد getBroadcast، برودکست موردنظر در PendingIntent تعریف می‌شود.
پارامتر سوم getBroadcast از جنس اینتنت بوده که شامل اکشن‌های SMS_SENT و SMS_DELIVERED می‌باشد که قبلا در برودکست‌ها تعیین کرده بودیم. همانطور که از نحوه نامگذاری PendingIntent ها پیداست، مورد اول برای اجرای برودکست ارسال پیامک و مورد دوم برای اجرای برودکست تحویل پیامک استفاده خواهد شد.
در انتها لازم است این دو PendingIntent در smsManager جایگزین مقدارهای null شوند:

smsManager.sendTextMessage("+989158888888", null, "تست ارسال پیامک", sentSMS, deliverSMS);

بنابراین با ارسال پیامک توسط SmsManager در آینده و هر زمانی که گزارش مربوط به وضعیت ارسال و همچنین تحویل پیامک توسط سیستم عامل منتشر شود، توسط BroadcastReceiver ها دریافت شده و پیغام مناسب روی صفحه ظاهر خواهد شد.
در نهایت، متن پیغام Toast که بعد از smsManager قرار گرفته را از “پیامک ارسال شد” به “ارسال پیامک آغاز شد” تغییر می‌دهم تا از پیغامی که در برودکست ارسال پیامک تعریف شده قابل تشخیص باشد.
مجدد پروژه را اجرا کرده و روی دکمه ارسال پیامک کلیک می‌کنم:

مشاهده می‌کنید گزارش مربوط به ارسال و تحویل پیامک توسط برنامه دریافت و پیغام آن نمایش داده شد.
کد نهایی اکتیویتی تا اینجای کار:

MainActivity.java

package ir.android_studio.sendsms;

import androidx.annotation.NonNull;
import androidx.appcompat.app.AlertDialog;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;
import android.Manifest;
import android.app.Activity;
import android.app.PendingIntent;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.DialogInterface;
import android.content.Intent;
import android.content.IntentFilter;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.telephony.SmsManager;
import android.widget.Button;
import android.widget.Toast;

public class MainActivity extends AppCompatActivity {

    Button sendBtn;
    private final int SMS_REQUEST_CODE = 100;
    String SMS_SENT = "SMS_SENT";
    String SMS_DELIVERED = "SMS_DELIVERED";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        sendBtn = findViewById(R.id.sms_btn);

        sendBtn.setOnClickListener(view -> {

            if (ContextCompat.checkSelfPermission(MainActivity.this, Manifest.permission.SEND_SMS) != PackageManager.PERMISSION_GRANTED) {

                requestSendSMSpermission();

            } else {

                sendMessage();

            }

        });

    }

    private void sendMessage() {

        try {

            //Broadcast for Sent SMS
            registerReceiver(new BroadcastReceiver() {
                @Override
                public void onReceive(Context context, Intent intent) {

                    String state = "";
                    switch (getResultCode()) {
                        case Activity.RESULT_OK:
                            state = "پیامک ارسال شد";
                            break;
                        case SmsManager.RESULT_ERROR_GENERIC_FAILURE:
                            state = "یک خطای عمومی رخ داد";
                            break;
                        case SmsManager.RESULT_ERROR_NO_SERVICE:
                            state = "اپراتور در دسترس نیست";
                            break;
                        case SmsManager.RESULT_ERROR_NULL_PDU:
                            state = " پروتکل PDU در دسترس نیست";
                            break;
                        case SmsManager.RESULT_ERROR_RADIO_OFF:
                            state = "سیم کارت در دسترس نیست";
                            break;
                    }
                    Toast.makeText(context, state, Toast.LENGTH_SHORT).show();
                }
            }, new IntentFilter(SMS_SENT));

            //Broadcast for Delivered SMS
            registerReceiver(new BroadcastReceiver() {
                @Override
                public void onReceive(Context context, Intent intent) {
                    String state = "";
                    switch (getResultCode()) {
                        case Activity.RESULT_OK:
                            state = "پیامک تحویل داده شد";
                            break;
                        case Activity.RESULT_CANCELED:
                            state = "پیامک تحویل داده نشد";
                            break;
                    }
                    Toast.makeText(context, state, Toast.LENGTH_SHORT).show();
                }
            }, new IntentFilter(SMS_DELIVERED));

            PendingIntent sentSMS = PendingIntent.getBroadcast(this, 0, new Intent(SMS_SENT), 0);
            PendingIntent deliverSMS = PendingIntent.getBroadcast(this, 0, new Intent(SMS_DELIVERED), 0);

            SmsManager smsManager = SmsManager.getDefault();
            smsManager.sendTextMessage("+989158888888", null, " تست ارسال پیامک", sentSMS, deliverSMS);

            Toast.makeText(MainActivity.this, " ارسال پیامک آغاز شد", Toast.LENGTH_SHORT).show();

        } catch (Exception e) {

            Toast.makeText(MainActivity.this, " پیامک ارسال نشد", Toast.LENGTH_SHORT).show();

        }

    }

    private void requestSendSMSpermission() {

        if (ActivityCompat.shouldShowRequestPermissionRationale(MainActivity.this, Manifest.permission.SEND_SMS)) {

            new AlertDialog.Builder(this)
                    .setTitle("درخواست مجوز")
                    .setMessage("برای عملکرد صحیح برنامه باید دسترسی به ارسال پیامک تایید شود")
                    .setPositiveButton("موافقم", new DialogInterface.OnClickListener() {
                        @Override
                        public void onClick(DialogInterface dialogInterface, int i) {

                            reqPermission();

                        }
                    })
                    .setNegativeButton("لغو", new DialogInterface.OnClickListener() {
                        @Override
                        public void onClick(DialogInterface dialogInterface, int i) {

                            dialogInterface.dismiss();

                        }
                    })
                    .create()
                    .show();

        } else {

            reqPermission();

        }

    }

    private void reqPermission() {

        ActivityCompat.requestPermissions(MainActivity.this, new String[] {Manifest.permission.SEND_SMS}, SMS_REQUEST_CODE);

    }

    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {

        if (requestCode == SMS_REQUEST_CODE) {

            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {

                sendMessage();

            } else {

                Toast.makeText(this, " مجوز رد شد", Toast.LENGTH_SHORT).show();

            }

        }

    }

}

بررسی وضعیت سیم کارت قبل از ارسال پیامک

در قسمت قبل پس از ارسال پیامک و توسط کلاس SmsManager وضعیت سیم کارت بررسی می‌شد و در صورت عدم امکان ارسال SMS علت عدم ارسال توسط BroadcastReceiver مشخص می‌شد.
اما با استفاده از کلاس TelephonyManager و متد getSimState می‌توانیم قبل از اقدام به ارسال SMS هم وضعیت سیم کارت را از سیستم عامل دریافت کرده و بر اساس آن عملیاتی انجام داد. برای مثال تا زمانی که سیم کارت در دسترس نباشد، دکمه ارسال پیامک در حالت غیر فعال (Disable) قرار گیرد و یا سایر روش‌های آگاه سازی کاربر به در دسترس نبودن سیم کارت که موضوع این جلسه نیست.
البته کاربرد getSimState محدود به قبل از ارسال پیامک نمی‌شود. برنامه ما ممکن است به هر دلیلی نیاز به فعال بودن سیم کارت داشته باشد؛ مانند دریافت رمز یکبار مصرف. بنابراین می‌توانیم کاربر را از وضعیت سیم کارت دستگاه مطلع کنیم.
یک متد با نام دلخواه simState درون اکتیویتی تعریف و به صورت زیر تکمیل می‌کنم:

public void simState() {
    TelephonyManager telephonyManager = (TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE);
    int SIM_STATE = telephonyManager.getSimState();

    if (SIM_STATE == TelephonyManager.SIM_STATE_READY) {
        Toast.makeText(this, "سیم کارت در دسترس است", Toast.LENGTH_SHORT).show();
    }
    else {
        String state = "";
        switch (SIM_STATE) {
            case TelephonyManager.SIM_STATE_ABSENT:
                state = "Sim absent";
                break;
            case TelephonyManager.SIM_STATE_NETWORK_LOCKED:
                state = "Network locked";
                break;
            case TelephonyManager.SIM_STATE_PIN_REQUIRED:
                state = "Pin required";
                break;
            case TelephonyManager.SIM_STATE_PUK_REQUIRED:
                state = "PUK required";
                break;
            case TelephonyManager.SIM_STATE_UNKNOWN:
                state = "Unknown";
                break;
        }
        Toast.makeText(this, state, Toast.LENGTH_SHORT).show();
    }
}

در کد فوق با استفاده از متد getSimState وضعیت سیم کارت بررسی می‌شود. چنانچه سیم کارت در دسترس باشد حالت SIM_STATE_READY برگردانده می‌شود. در غیر اینصورت یکی از ۵ حالت تعریف شده در قسمت دوم شرط برگردانده شده و پیغام مربوط به آن حالت در Toast نمایش داده خواهد شد.
برای اجرای متد simState() کافیست آنرا در متد onCreate() اکتیویتی فراخوانی کنیم.
پروژه را یکبار در حالتی که سیم کارت درون شیار دستگاه قرار دارد و بار دوم در حالتی که سیم کارت موجود نیست اجرا می‌کنم:

MainActivity.java

package ir.android_studio.sendsms;

import androidx.annotation.NonNull;
import androidx.appcompat.app.AlertDialog;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;
import android.Manifest;
import android.app.Activity;
import android.app.PendingIntent;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.DialogInterface;
import android.content.Intent;
import android.content.IntentFilter;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.telephony.SmsManager;
import android.telephony.TelephonyManager;
import android.widget.Button;
import android.widget.Toast;

public class MainActivity extends AppCompatActivity {

    Button sendBtn;
    private final int SMS_REQUEST_CODE = 100;
    String SMS_SENT = "SMS_SENT";
    String SMS_DELIVERED = "SMS_DELIVERED";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

	simState();

        sendBtn = findViewById(R.id.sms_btn);

        sendBtn.setOnClickListener(view -> {

            if (ContextCompat.checkSelfPermission(MainActivity.this, Manifest.permission.SEND_SMS) != PackageManager.PERMISSION_GRANTED) {

                requestSendSMSpermission();

            } else {

                sendMessage();

            }

        });

    }

    private void sendMessage() {

        try {

            //Broadcast for Sent SMS
            registerReceiver(new BroadcastReceiver() {
                @Override
                public void onReceive(Context context, Intent intent) {

                    String state = "";
                    switch (getResultCode()) {
                        case Activity.RESULT_OK:
                            state = "پیامک ارسال شد";
                            break;
                        case SmsManager.RESULT_ERROR_GENERIC_FAILURE:
                            state = "یک خطای عمومی رخ داد";
                            break;
                        case SmsManager.RESULT_ERROR_NO_SERVICE:
                            state = "اپراتور در دسترس نیست";
                            break;
                        case SmsManager.RESULT_ERROR_NULL_PDU:
                            state = " پروتکل PDU در دسترس نیست";
                            break;
                        case SmsManager.RESULT_ERROR_RADIO_OFF:
                            state = "سیم کارت در دسترس نیست";
                            break;
                    }
                    Toast.makeText(context, state, Toast.LENGTH_SHORT).show();
                }
            }, new IntentFilter(SMS_SENT));

            //Broadcast for Delivered SMS
            registerReceiver(new BroadcastReceiver() {
                @Override
                public void onReceive(Context context, Intent intent) {
                    String state = "";
                    switch (getResultCode()) {
                        case Activity.RESULT_OK:
                            state = "پیامک تحویل داده شد";
                            break;
                        case Activity.RESULT_CANCELED:
                            state = "پیامک تحویل داده نشد";
                            break;
                    }
                    Toast.makeText(context, state, Toast.LENGTH_SHORT).show();
                }
            }, new IntentFilter(SMS_DELIVERED));

            PendingIntent sentSMS = PendingIntent.getBroadcast(this, 0, new Intent(SMS_SENT), 0);
            PendingIntent deliverSMS = PendingIntent.getBroadcast(this, 0, new Intent(SMS_DELIVERED), 0);

            SmsManager smsManager = SmsManager.getDefault();
            smsManager.sendTextMessage("+989158888888", null, " تست ارسال پیامک", sentSMS, deliverSMS);

            Toast.makeText(MainActivity.this, " ارسال پیامک آغاز شد", Toast.LENGTH_SHORT).show();

        } catch (Exception e) {

            Toast.makeText(MainActivity.this, " پیامک ارسال نشد", Toast.LENGTH_SHORT).show();

        }

    }

    private void requestSendSMSpermission() {

        if (ActivityCompat.shouldShowRequestPermissionRationale(MainActivity.this, Manifest.permission.SEND_SMS)) {

            new AlertDialog.Builder(this)
                    .setTitle("درخواست مجوز")
                    .setMessage("برای عملکرد صحیح برنامه باید دسترسی به ارسال پیامک تایید شود")
                    .setPositiveButton("موافقم", new DialogInterface.OnClickListener() {
                        @Override
                        public void onClick(DialogInterface dialogInterface, int i) {

                            reqPermission();

                        }
                    })
                    .setNegativeButton("لغو", new DialogInterface.OnClickListener() {
                        @Override
                        public void onClick(DialogInterface dialogInterface, int i) {

                            dialogInterface.dismiss();

                        }
                    })
                    .create()
                    .show();

        } else {

            reqPermission();

        }

    }

    private void reqPermission() {

        ActivityCompat.requestPermissions(MainActivity.this, new String[] {Manifest.permission.SEND_SMS}, SMS_REQUEST_CODE);

    }

    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {

        if (requestCode == SMS_REQUEST_CODE) {

            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {

                sendMessage();

            } else {

                Toast.makeText(this, " مجوز رد شد", Toast.LENGTH_SHORT).show();

            }

        }

    }

    public void simState() {
    TelephonyManager telephonyManager = (TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE);
    int SIM_STATE = telephonyManager.getSimState();

    if (SIM_STATE == TelephonyManager.SIM_STATE_READY) {
        Toast.makeText(this, "سیم کارت در دسترس است", Toast.LENGTH_SHORT).show();
    }
    else {
        String state = "";
        switch (SIM_STATE) {
            case TelephonyManager.SIM_STATE_ABSENT:
                state = "Sim absent";
                break;
            case TelephonyManager.SIM_STATE_NETWORK_LOCKED:
                state = "Network locked";
                break;
            case TelephonyManager.SIM_STATE_PIN_REQUIRED:
                state = "Pin required";
                break;
            case TelephonyManager.SIM_STATE_PUK_REQUIRED:
                state = "PUK required";
                break;
            case TelephonyManager.SIM_STATE_UNKNOWN:
                state = "Unknown";
                break;

            }
        	Toast.makeText(this, state, Toast.LENGTH_SHORT).show();
        }
    }

}

در این جلسه ارسال پیامک (SMS) در برنامه نویسی اندروید را به همراه نحوه‌ی دریافت گزارش ارسال و تحویل و همچنین وضعیت سیم کارت دیوایس اندرویدی بررسی کردیم. امیدوارم مفید واقع شود.
موفق و پیروز باشید.

مطالعه‌ی بیشتر:

https://developer.android.com/reference/android/telephony/SmsManager
https://developer.android.com/reference/android/app/PendingIntent

توجه : سورس پروژه درون پوشه Exercises قرار دارد

نوشته ارسال پیامک (SMS) در برنامه اندرویدی + سورس پروژه اولین بار در اندروید استودیو پدیدار شد.

این جلسه در قالب PDF و در ۱۰۷ صفحه تهیه شده که در ادامه چند صفحه‌ ابتدایی را مشاهده می‌کنید:

ConstraintLayout چیست؟

به نام خدا. ConstraintLayout برای اولین بار در کنفرانس Google I/O در سال ۲۰۱۶ معرفی شد. اصلی ترین هدف گوگل از معرفی این Layout جدید، امکان طراحی لایه‌های پیچیده و در عین حال flat (تخت) بود؛ بر خلاف Layout های قبلی که برای طراحی یک صفحه ناگزیر به استفاده از لایه‌های تو در تو و سلسله مراتبی بودیم.

این یعنی دیگر لازم نیست چندین لایه RelativeLayout و LinearLayout و… درون یکدیگر و به صورت تو در تو تعریف شود تا بتوان یک صفحه چند قسمتی را ساخت. بنابراین علاوه بر سادگی پیاده سازی این لایه و کاهش حجم نهایی کدهای آن، در طراحی صفحات با ConstraintLayout کارایی و performance اکتیویتی بهبود یافته و می‌تواند در افزایش سرعت نمایش UI روی دستگاه کاربر تاثیر مثبت بگذارد.
ConstraintLayout از اندروید استودیو ۲٫۲ اضافه شد و نسخه ابتدایی آن Beta 1 نام داشت. در طی این چند سال مرتبا اصلاحاتی روی آن انجام و همچنین قابلیت‌های جدیدی نیز اضافه شده است. خبر خوب اینکه این لایه از API 9 به بعد پشتیبانی می‌شود بنابراین مطمئن خواهیم بود تمامی دستگاه‌های اندرویدی که در حال حاضر در اختیار افراد هست به خوبی می‌توانند صفحاتی که با این layout طراحی شده‌اند را نمایش دهند.
در ConstraintLayout می‌توانیم وضعیت قرارگیری تمامی view/widget ها را نسبت به یکدیگر و یا parent شان تعیین کنیم. برای مثال می‌توانیم یک TextView را به نحوی در زیر یک ImageView متصل کنیم که در جهت افقی، متن همواره در مرکز تصویر قرار گیرد. یا اینکه یک یا چند view بر اساس سایز صفحه نمایش دستگاه، چه از جهت افقی و چه عمودی همواره در مرکز قرار گرفته و علاوه بر آن، فاصله آنها از یکدیگر نیز درصدی ثابت باشد.
این یعنی یک انعطاف پذیری بسیار بالا که تا حدود زیادی مشابه طراحی صفحات واکنشگرا یا Responsive در صفحات وب است.
فکر می‌کنم هرچه اینجا بیشتر توضیح بدهم بیشتر هم شما را گیج می‌کنم! بنابراین بهتر است سراغ محیط توسعه اندروید استودیو رفته و امکانات این لایه قدرتمند را در عمل بررسی کنیم.
توجه داشته باشید در نسخه‌های ابتدایی اندروید استودیو که ConstraintLayout اضافه شده بود می‌بایست ابزار آن به صورت جداگانه در SDK و در زیرمجموعه Support Repository دریافت و نصب می‌شد اما در نسخه‌های اخیر، این گزینه از لیست SDK Tools حذف شده و با سایر ابزار اصلی توسعه اندروید ادغام شده است.
قبل از هرچیز توجه داشته باشید در برخورد اول قطعا کار با این layout مقداری گیج کننده خواهد بود بنابراین لازم است بارها و بارها تمرین کرده و خروجی کار را مقایسه کنید تا کاربرد هر قابلیت را بتوانید به درستی درک نمائید.

نحوه طراحی صفحات رابط کاربری اندروید با ConstraintLayout

قبل از هرچیز ابتدا طبق مبحث آموزش ساخت پروژه در اندروید استودیو یک پروژه اندرویدی با نام ConstraintLayout می‌سازم. اکتیویتی را از نوع Empty Activity و زبان را Java انتخاب کردم.
کتابخانه این layout به صورت پیش فرض در بلاک dependencies فایل build.gradle(app) پروژه اندرویدی قرار دارد:

dependencies {
    implementation 'androidx.constraintlayout:constraintlayout:2.0.4'
}

در زمان نگارش این آموزش، نسخه ۲٫۰٫۴ جدیدترین نسخه از این ViewGroup است.
Layout پیش فرض اکتیویتی پروژه از نوع ConstraintLayout بوده که در قسمت Component tree قابل مشاهده است:

محیط پیش نمایش در دو حالت Design و Blueprint قابل نمایش است که به منظور خلوت بودن صفحه در حین آموزش تنها از حالت Design استفاده می‌کنم.

خطوط اتصال و گره‌ها در ConstraintLayout

از ساده ترین مثال شروع می‌کنم. ملاحظه می‌کنید یک TextView به طور پیش فرض در مرکز صفحه پیش نمایش با عنوان Hello World! قرار گرفته. موس را روی TextView قرار می‌دهم:

این TextView توسط ۴ خط اتصال به ۴ لبه‌ی صفحه متصل شده است. حالا روی TextView کلیک می‌کنم:

ملاحظه می‌کنید خطوط اتصال پررنگ شده و نقاط اتصال خطوط به ویجت مدنظر نیز به شکل دایره‌های توپر نمایش داده می‌شود. هر کدام از این دایره‌ها را یک گره یا node می‌نامیم. علت قرار گرفتن این TextView در مرکز صفحه این است که هر ۴ گره آن به چهار جهت صفحه نمایش متصل شده.
قبل از انجام هر کاری کد xml صفحه را بررسی می‌کنیم:

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Hello World!"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

ملاحظه می‌کنید یک TextView با تعدادی ویژگی درون layout از جنس ConstraintLayout قرار گرفته است. به عبارتی این layout والد یا parent ویجت TextView است.

app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintLeft_toLeftOf="parent"
app:layout_constraintRight_toRightOf="parent"
app:layout_constraintTop_toTopOf="parent"

این چهار attribute موقعیت مکانی TextView را نسبت به والد خود تعیین می‌کند. یعنی به ازاء هر خط اتصالی که از گره‌های ویجت به یکی از کناره‌های صفحه نمایش کشیده شده یکی از این ویژگی‌ها به کد TextView اضافه شده است.

app:layout_constraintBottom_toBottomOf="parent"

اگر به نحوه نامگذاری هر کدام دقت کنید کاربرد آن را متوجه خواهید شد.
Bottom to Bottom of parent یعنی پایینِ TextView به پایینِ parent متصل شود. و به همین ترتیب برای ۳ مورد دیگر. نتیجه این می‌شود که ویجت از بالا و پایین به یک اندازه و همچنین از چپ و راست هم به یک اندازه فاصله گرفته بنابراین در مرکز صفحه قرار می‌گیرد.
با توجه به اینکه در اینجا برای تعیین فاصله از واحدهای اندازه گیری استفاده نشده لذا یک رابط کاربری ساده و انعطاف پذیر داریم که در هر صفحه نمایشی اجرا شود اعم از کوچک و بزرگ یا افقی و عمودی، همواره این TextView در مرکز صفحه قرار خواهد گرفت.
اگر یکی از این خطوط حذف شود چه اتفاقی خواهد افتاد؟ می‌خواهم خط بالا را حذف کنم. برای اینکار هم می‌توان در حالت کد، ویژگی layout_constraintTop_toTopOf را از تکست ویو حذف کرد هم اینکه در حالت دیزاین، خط بالا را انتخاب کرده و delete ‌کنیم. همچنین اگر روی هریک از خطوط راست کلیک کنیم گزینه‌های مختلفی نمایش داده می‌شود که یکی از آنها Delete است:

مشاهده می‌کنید با حذف خط اتصال بالا، TextView از جهت افقی در مرکز قرار دارد اما در جهت عمودی به پایین صفحه چسبیده است. برای در مرکز قرار گرفتن ویجت کافی است دوباره ویژگی layout_constraintTop_toTopOf با مقدار parent را در ویرایشگر کد اضافه کرده و یا در محیط ویژوال به وسیله عمل Drag & Drop دایره یا گره بالای ویجت را گرفته و روی لبه بالای صفحه رها کنم:

در نهایت مجدد توانستم ویجت را نسبت به بالا و پایین در مرکز قرار دهم.
برای مشاهده جزئیات بیشتر روی گزینه Attributes نوار سمت راست محیط دیزاین کلیک می‌کنم. سپس روی صفحه پیش نمایش یا Component tree ویجت TextView را انتخاب می‌کنم تا ویژگی‌های مرتبط با آن نمایش داده شود:

در قسمت Declared Attributes عینا مواردی که در کد TextView دیدیم لیست شده و می‌توان هرکدام را تغییر داد.
در قسمت Layout امکانات بیشتری برای اعمال تغییرات وجود دارد. در چهار جهت آیکون مربعی شکل که نماد ویجت انتخاب شده یعنی TextView است، فیلدهای عددی دیده می‌شود که در حالت پیش فرض عدد صفر را نشان می‌دهند. این اعداد، فاصله یا margin را از جهت‌هایی که توسط خط اتصال به والد یا یک ویجت دیگر متصل شده تعیین می‌کنند.
در اینجا که ویجت ما در مرکز صفحه قرار گرفته تعیین فاصله اهمیتی ندارد اما در ادامه آموزش و هنگامی که بخواهیم یک ویجت را در کنار یک ویجت دیگر قرار دهیم از این ویژگی استفاده خواهیم کرد.

تعیین فاصله از چپ و پایین توسط Bias

در سمت چپ و پایین دو گزینه در کنار عدد مارجین قرار دارد که توسط آن و با حرکت دادن دایره روی خط، میزان فاصله از چهار جهت را می‌توان تغییر داد. این قابلیت Bias نام دارد. دقت داشته باشید در اینجا خبری از واحدهای px و dp نیست بلکه بر اساس درصد تعیین می‌شود. به صورت پیش فرض هردو Bias روی ۵۰ قرار دارد یعنی مرکز صفحه.
اگر بخاطر داشته باشید در کد مربوط به TextView ویژگی با نام Bias وجود نداشت. این یعنی مقدار پیش فرض Bias برای یک ویجت همین ۵۰% یا مقدار ۰٫۵ است و صرفا در صورتی این ویژگی به ویجت اضافه خواهد شد که مقداری غیر از ۵۰ برای آن درنظر بگیریم.
برای تمرین، ویجت روی صفحه یا همین گزینه پایین که مربوط به جهت افقی هست را مقداری به سمت چپ بکشید:

ملاحظه می‌کنید عدد Horizontal Bias به ۲۵ تغییر کرد و ویجت هم در جهت افق به اندازه ۲۵ درصد به سمت چپ نزدیکتر شد. حالا اگر کد ویجت را دوباره بررسی کنید خط زیر به آن اضافه شده:

app:layout_constraintHorizontal_bias="0.25"

در محیط ویژوال عدد از ۰ تا ۱۰۰ و در کد از ۰ تا ۱ تعیین می‌شود. یعنی ۲۵ درصد برای Bias افقی (Horizontal) برابر است با مقدار ۰٫۲۵ برای ویژگی آن در کدها.
صفحه پیش نمایش را در حالت افقی (Landscape) قرار می‌دهم:

باز هم ویجت در فاصله ۲۵ درصدی از سمت چپ صفحه قرار گرفته و انعطاف پذیری ConstraintLayout را ثابت می‌کند.

تعیین عرض و ارتفاع Widget یا View ها

عرض و ارتفاع هر ویجتی که به layout اضافه می‌شود ابتدا wrap_content است؛ یعنی به اندازه محتوای درون خودش جا می‌گیرد. اما دو حالت دیگر هم قابل انجام است.

در تصویر بالا مشاهده می‌کنید با بردن نشانگر بر روی یکی از فاصله‌های افقی عبارت Wrap Content نمایش داده می‌شود. یکبار روی یکی از آنها کلیک می‌کنم:

نماد فاصله‌های افقی از دو فلش به یک خط ممتد تغییر پیدا کرد و عبارت Fixed را نمایش می‌دهد. همچنین در قسمت Declared Attributes مقدار width از wrap_content به ۷۶dp برای من تغییر داده شد یعنی اندروید استودیو یک مقدار پیش فرض در واحد dp را درنظر گرفت. حالا من می‌توانم مقدار مدنظر خودم را بجای ۷۶ وارد کنم.
در مواقعی به این حالت نیاز داریم که بخواهیم برای یک ویجت عرض یا ارتفاع مشخص و ثابتی را درنظر بگیریم و نباید اندازه آن به صفحه نمایش یا حالت قرار گیری آن بستگی داشته باشد.
یک مرتبه دیگر روی نماد فاصله افقی کلیک می‌کنم:

اینبار نوع فاصله گذاری به Match Constraints تغییر پیدا کرد. این حالت همان match_parents در layout هایی مانند RelativeLayout است اما در ConstraintLayout برای اینکه یک ویجت تمام عرض یا ارتفاع در دسترس را اشغال کند بجای match_parent مقدار ۰dp باید داده شود که اندروید استودیو این تغییر را به صورت خودکار برای من انجام داد:

با انجام این تغییر، ویجت از دو طرف چپ و راست به محلی چسبید که خطوط اتصال برقرار است. در تصویر زیر هنوز هم خطوط اتصال افقی فعال هستند اما چون فاصله‌ای بین TextView و لبه‌های صفحه پیش نمایش وجود ندارد قابل مشاهده نیست. البته از گره‌های تو پر می‌توان فعال بودن این دو را تشخیص داد.

خب! حالا که تا حدودی با کلیت کار آشنا شدیم ادامه آموزش را در قالب چند مثال عملی طراحی صفحات با ConstraintLayout پیش می‌برم تا درک بهتری از امکانات آن داشته باشید.
از مسیر New > Layout Resource file یک layout جدید با نام layout_two.xml به پروژه اضافه می‌کنم. هر قسمت را در یک فایل جداگانه توضیح می‌دهم تا همه کدها در سورس پروژه ضمیمه شده را در اختیار داشته باشید.
یک ویجت Button را از پالت ابزار کشیده و در مرکز صفحه پیش نمایش قرار می‌دهم:

اینجا ظاهرا مشکلی نیست و پس از رها کردن، دکمه در مرکز صفحه باقی می‌ماند. حالا می‌خواهم پروژه را اجرا کنم تا خروجی کار را روی دیوایس اندرویدی هم ببینیم. در MainActivity.java فایل layout_two را جایگزین activity_main می‌کنم تا هنگام اجرای پروژه روی دیوایس نمایش داده شود.

MainActivity.java

package ir.android_studio.constraintlayout;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.layout_two);
    }
}

پروژه را روی شبیه ساز Genymotion اجرا می‌کنم:

برخلاف آنچه در Preview اندروید استودیو دیدیم که دکمه در مرکز طولی و عرضی صفحه نمایش قرار گرفته بود، روی دیوایس اندرویدی دکمه در گوشه صفحه قرار گرفته است. به سورس layout دقت کنید:

layout_two.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <Button
        android:id="@+id/button2"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Button"
        tools:layout_editor_absoluteX="156dp"
        tools:layout_editor_absoluteY="342dp" />
</androidx.constraintlayout.widget.ConstraintLayout>

دو ویژگی layout_editor_absoluteX و layout_editor_absoluteY فقط در صفحه پیش نمایش اندروید استودیو کاربرد دارند و تا زمانی که خطوط constraint برای ویو یا ویجت ساخته نشود موقعیت آن در صفحه تغییری نخواهد کرد. گره‌های چپ و راست دکمه را به دو طرف صفحه متصل می‌کنم:

مشاهده می‌کنید دکمه در جهت افقی درست در مرکز صفحه قرار گرفته. ویژگی‌های layout_editor_absolute تنها زمانی فعال می‌شود که خطوط اتصال در آن جهت وجود نداشته باشد. بنابراین با اضافه شدن دو خط چپ و راست، ویژگی layout_editor_absoluteX از دکمه حذف شد و فقط layout_editor_absoluteY باقی ماند:

<Button
    android:id="@+id/button2"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Button"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    tools:layout_editor_absoluteY="342dp" />

در حال حاضر نحوه نمایش وضعیت constraint ویجت دکمه به اینصورت است:

در جهت بالا و پایین نماد + وجود دارد که به وضوح نشان می‌دهد در این گره‌ها اتصالی انجام نشده است. البته اگر اینجا روی + کلیک کنیم علاوه بر ایجاد خط اتصال، یک فاصله (margin) به مقداری که قبلا در layout_editor_absoluteY تعریف شده نیز اضافه خواهد شد.
به عبارت دیگر layout_marginTop جایگزین ویژگی layout_editor_absoluteY می‌شود:

بنابراین بهتر است ایجاد خط اتصال به همان شیوه Drag & Drop روی صفحه پیش نمایش انجام شود یا در صورت ایجاد آن از طریق دکمه + لازم است مقدار margin صفر و یا به عدد دلخواه اصلاح شود.
در نوار بالای پیش نمایش چندین گزینه وجود دارد که دو مورد را در اینجا و مابقی را بعدا توضیح خواهم داد.

حذف یکباره تمامی Constraint ها

گزینه Clear All Constraints همانطور که از نامش پیداست تمامی اتصالاتی که درون layout بر روی ویجت‌ها اعمال شده را به یکباره حذف می‌کند. این مورد مواقعی کاربرد دارد که تعدادی تغییرات در صفحه انجام داده‌ایم و لازم است همگی اصلاح شوند. با استفاده از این گزینه همه تغییرات قبلی حذف شده و لازم نیست یک به یک constraint ها را حذف کنیم.
همچنین کاربرد دیگر آن هنگامی است که یک layout که قبلا با استفاده از یک ViewGroup دیگر مانند LinearLayout طراحی شده را بخواهیم به ConstraintLayout تبدیل کنیم.

تبدیل ViewGroup های دیگر به ConstraintLayout

برای مثال قصد داریم رابط کاربری مربوط به آموزش دیتابیس در اندروید که قبلا با استفاده از RelativeLayout ساخته بودیم را به ConstraintLayout تبدیل کنیم. در قسمت Component Tree روی ViewGroup راست کلیک کرده و گزینه Convert RelativeLayout to ConstraintLayout را انتخاب می‌کنم:

پس از انجام عملیات تبدیل، اندروید استودیو به صورت خودکار اتصالات Constraint را بر اساس چینش قبلی ویجت‌ها انجام می‌دهد اما خب عمدتا و بخصوص در لایه‌های پیچیده، آن چیزی که ما انتظارش را داریم اتفاق نمی‌افتد و لازم است خودمان نحوه چیدمان المان‌ها را به صورت دستی انجام دهیم.

ایجاد خودکار Constraint ها

گزینه Infer Constraints عملی متضاد با Clear All Constraints را انجام می‌دهد. واژه infer به معنی “حدس زدن” است. یعنی در یک layout از جنس ConstraintLayout که یک یا چندین ویجت بدون خطوط اتصال و مابقی قابلیت‌های آن اضافه شده، با کلیک روی این گزینه، اندروید استودیو به صورت حدسی تنظیمات و خطوط اتصال را برای آنها اعمال می‌کند اما همانطور که در قسمت قبل اشاره شد، این تنظیمات عموما رضایت بخش نبوده و در عمل کاربرد زیادی نخواهد داشت.
فعلا با ویجت دکمه کاری ندارم و آنرا از صفحه حذف می‌کنم.
یک گزینه دیگر با نام Default Margins در بالای صفحه Preview وجود دارد:

تعیین فاصله یا Margin پیش فرض

در طراحی یک layout برای ایجاد فاصله بین المان‌های مختلف از ویژگی Margin استفاده می‌کنیم. معمولا فاصله‌ای که در یک layout برای المان‌های مختلف استفاده می‌شود یکسان است تا چینش عناصر در رابط کاربری منظم و یکپارچه باشد.
مقدار Defalut Margin به طور پیش فرض روی عدد ۰ تنظیم شده. من این مقدار را روی ۱۶dp تنظیم می‌کنم و کار را ادامه می‌دهم.
ابتدا یک ImageView به صفحه اضافه می‌کنم:

در قسمت Attributes عرض این ویجت را ۰dp یا همان Match Constraint و ارتفاع را ۲۰۰dp تعیین می‌کنم. همچنین ویژگی scaleType را بر روی centerCrop تنظیم می‌کنم تا در هر اندازه‌ای از صفحه نمایش، تصویر به طور کامل در محل ImageView قرار گرفته و فضای خالی در اطراف آن ایجاد نشود:

سپس گره‌های سه جهت بالا و چپ و راست را به سه طرف والد یا به عبارتی لبه‌های صفحه نمایش متصل می‌کنم:

در تصویر بالا ملاحظه می‌کنید دو گره متصل شده یک فاصله ۱۶dp از لبه گرفته‌اند. قبلا این عدد را در Defalut Margin تعریف کرده بودیم. همچنین بعد از اینکه گره‌های بالا و سمت چپ را متصل کردم، به دلیل اینکه قبلا عرض تصویر به اندازه عرض صفحه پیش نمایش کشیده شده بود، گره سمت راست در داخل کادر قرار ندارد. اگر موس را بر روی خط چین سمت راست قرار داده و آنرا به سمت لبه راست صفحه بکشم خط اتصال برقرار می‌شود. یا اینکه در کادر Attributes در قسمت Constraint Widget روی نماد + سمت راست ویجت ImageView کلیک می‌کنم. اینجا فاصله ۱۶dp به طور خودکار اعمال نشد بنابراین به صورت دستی وارد می‌کنم. خروجی نهایی کار به اینصورت خواهد بود:

layout_two.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent" >

    <ImageView
        android:id="@+id/imageView5"
        android:layout_width="0dp"
        android:layout_height="200dp"
        android:layout_marginStart="16dp"
        android:layout_marginLeft="16dp"
        android:layout_marginTop="16dp"
        android:layout_marginEnd="16dp"
        android:layout_marginRight="16dp"
        android:scaleType="centerCrop"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:srcCompat="@drawable/img_22" />

</androidx.constraintlayout.widget.ConstraintLayout>

تا اینجای کار ما یک تصویر به بالای صفحه اضافه کردیم که در هر اندازه‌ای از صفحه نمایش، از سه جهت فاصله ۱۶dp خواهد داشت.

در قدم بعد قصد دارم یک آیکون یا تصویر را به نحوی روی تصویر فعلی قرار دهم که مرکز آن، لبه پایینی این ImageView باشد. ابتدا یک ImageView دیگر را از پالت روی صفحه پیش نمایش کشیده و یک آیکون یا تصویر را به دلخواه انتخاب می‌کنم:

کد این ویجت به اینصورت است:

<ImageView
    android:id="@+id/imageView6"
    android:layout_width="40dp"
    android:layout_height="40dp"
    android:background="#DFCD2E"
    android:padding="5dp"
    app:srcCompat="@android:drawable/stat_sys_speakerphone"
    tools:layout_editor_absoluteX="47dp"
    tools:layout_editor_absoluteY="244dp" />

حالا گره‌های بالا و پایین آیکون را به گره پایین ImageView قبلی متصل می‌کنم:

ملاحظه می‌کنید پس از انجام این کار، مرکز افقی تصویر دوم بر روی خط پایینی تصویر اول قرار گرفت. به همین سادگی!
در نهایت نود سمت چپ را هم به سمت چپ تصویر بزرگ متصل می‌کنم. با توجه به اینکه قبلا مقدار ۱۶dp را برای فاصله پیش فرض یا همان Default Margin تعیین کرده بودم، در اینجا نیز همین مقدار برای فاصله تعیین می‌شود:

حتما کد زیر و سایر کدهای هر قسمت از آموزش را به دقت بررسی کرده تا به خوبی درک کنید با انجام هر کار در محیط دیزاین، چه کدهایی به layout و ویجت‌ها اضافه شده است.

layout_two.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <ImageView
        android:id="@+id/imageView5"
        android:layout_width="0dp"
        android:layout_height="200dp"
        android:layout_marginStart="16dp"
        android:layout_marginLeft="16dp"
        android:layout_marginTop="16dp"
        android:layout_marginEnd="16dp"
        android:layout_marginRight="16dp"
        android:scaleType="centerCrop"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:srcCompat="@drawable/img_22" />

    <ImageView
        android:id="@+id/imageView6"
        android:layout_width="40dp"
        android:layout_height="40dp"
        android:layout_marginStart="16dp"
        android:layout_marginLeft="16dp"
        android:background="#DFCD2E"
        android:padding="5dp"
        app:layout_constraintBottom_toBottomOf="@+id/imageView5"
        app:layout_constraintStart_toStartOf="@+id/imageView5"
        app:layout_constraintTop_toBottomOf="@+id/imageView5"
        app:srcCompat="@android:drawable/stat_sys_speakerphone" />

</androidx.constraintlayout.widget.ConstraintLayout>

فرض کنید می‌خواهیم یک آیکون دیگر با همین وضعیت در سمت راست تصویر اضافه کنیم. تنها تفاوت در این است که در مرحله آخر بجای گره چپ، باید گره راست آیکون به گره راست تصویر بزرگ متصل شود.

همتراز کردن ویجت‌های متنی توسط Baseline

یکی دیگر از قابلیت‌های بسیار کاربردی ConstraintLayout در ویجت‌های متنی مانند EditText و Button ها استفاده می‌شود و Baseline نام دارد. توسط این ویژگی به سادگی می‌توانیم دو ویجت را در راستای افقی در یک تراز قرار دهیم.
یک TextView و یک EditText به صفحه اضافه می‌کنم:

قابلیت Baseline بصورت پیش فرض روی ویجت‌ها فعال نیست و با راست کلیک روی آن و انتخاب گزینه Show Baseline فعال می‌گردد:

پس از انجام این کار یک قسمت کپسولی شکل به وسط EditText اضافه شد:

با کشیدن آن به سمت وسط ویجت TextView کپسول Baseline این ویجت نیز ظاهر می‌شود. بنابراین خطی که از Baseline ویجت EditText کشیده شده را روی آن رها می‌کنم:

حالا این دو ویجت در یک تراز قرار گرفته‌اند به طوری که متن درون EditText کاملا همراستای متن TextView دیده می‌شود. با تغییر موقعیت TextView ویجت EditText هم در همان جهت حرکت می‌کند و تراز باز هم برقرار باقی می‌ماند.
منابع تکمیلی: Developer ، Developer ، Developer ، Developer ، Developer ، Medium

جهت مطالعه ادامه آموزش، فایل PDF را دانلود نمائید

توجه : سورس پروژه درون پوشه Exercises قرار دارد

با توجه به اینکه آموزش‌های پایه با قیمت پایین در اختیار کاربر قرار گرفته و درآمد حاصل صرف تامین هزینه‌های وب سایت و تهیه آموزش‌های آتی می‌شود، به اشتراک گذاری این فایل با دیگران خلاف اخلاق است.

نوشته طراحی صفحات با ConstraintLayout + سورس پروژه اولین بار در اندروید استودیو پدیدار شد.

قابلیت مکان یابی در ابزارهای هوشمند و بخصوص دستگاه‌های اندرویدی شامل موبایل و تبلت، به یکی از پرکاربردترین امکانات این ابزار بدل شده و در طیف گسترده‌ای از برنامه‌ها و به تناسب سرویسی که به کاربران ارائه می‌دهند، این قابلیت پیاده سازی شده است.
اپلیکیشن‌های حمل و نقل شامل درخواست تاکسی و پیک، فروشگاه‌های آنلاین و برنامه‌های مسیریاب نمونه‌هایی از کاربرد قابلیت مکان‌یابی کاربر را نشان می‌دهد. در این برنامه‌ها، موقعیت مکانی کاربر دریافت شده و متناسب با ماهیت و کاربرد برنامه، پردازش مربوطه انجام می‌پذیرد.
در این جلسه قصد دارم نحوه پیاده سازی قابلیت مکان یابی در اندروید توسط FusedLocationProviderClient را آموزش دهم که از زیرمجموعه‌های GoogleApi محسوب می‌شود.

این بخش شامل مباحث زیر می‌باشد:

• معرفی API مکان یابی گوگل با نام Fused location provider
• تعریف مجوز دسترسی به موقعیت مکانی در مانیفست پروژه
• استفاده از کلاس LocationRequest جهت ارسال درخواست مکان یابی در اندروید به همراه تنظیمات مدنظر
• استفاده از LocationSettingsRequest.Builder برای بیلد کردن تنظیمات درخواست
• دریافت پاسخ موقعیت مکانی توسط LocationCallback
• نحوه فعال و غیر فعال کردن دکمه‌ها
• نحوه استفاده از آیتم‌های مکان یابی در اندروید مانند GPS، WiFi و شبکه موبایل
• بررسی همخوانی امکانات مکان یابی دستگاه با آنچه برنامه ما نیاز دارد توسط SettingsClient
• تعیین مدت فاصله زمانی بین بروزرسانی‌های موقعیت مکانی
• نمایش دیالوگ فعالسازی قابلیت Location در صورت خاموش بودن آن
• توقف دریافت و بروزرسانی موقعیت مکانی توسط removeLocationUpdates
• توقف عملیات بروزرسانی موقعیت مکانی هنگام توقف اکتیویتی جهت کاهش مصرف انرژی

تصاویر نهایی پروژه:

این جلسه در قالب PDF و در ۳۴ صفحه تهیه شده که در ادامه چند صفحه‌ ابتدایی را مشاهده می‌کنید:

قابلیت مکان یابی در اندروید

برای مکان یابی در سیستم عامل اندروید نیاز به انجام کار پیچیده و نوشتن کدهای طولانی نداریم. به لطف گوگل، در Google Play services یک Location API با نام Fused location provider در دسترس توسعه دهندگان قرار داده شده که با پیاده سازی آن در اپلیکیشن، می‌توان آخرین موقعیت مکانی کاربر را بدست آورد و از آن درون برنامه استفاده کرد.
این API از داده‌های دریافتی از GPS (جی پی اس) و همچنین سایر آیتم‌هایی که برای تعیین موقعیت مکانی کاربر استفاده می‌شود مانند Wi-Fi و شبکه موبایل، اطلاعات مربوط به وضعیت فعلی دستگاه را دریافت کرده و مختصات آن را در دسترس برنامه‌هایی قرار می‌دهد که به این اطلاعات نیاز دارند. ضمن اینکه مختصات دائما بروز شده و می‌توانیم در فواصل مشخصی، مختصات جدید موقعیت دستگاه را مرتبا دریافت کنیم.

برای دریافت موقعیت مکانی کاربر به واسطه Google Play services لازم است از کلاس FusedLocationProviderClient در پروژه خود استفاده کنیم.
در این جلسه یک پروژه ساده را ایجاد می‌کنیم که با فعال شدن قابلیت مکان یابی در اندروید، به طور مستمر و هر ۱۰ ثانیه یکبار مختصات موقعیت مکانی دستگاه را نمایش می‌دهد.

پروژه نمایش موقعیت جغرافیایی در اندروید

قصد دارم یک پروژه ساده را تمرین و بررسی کنیم که دو Button و سه TextView در اکتیویتی تعریف شده است. با کلیک روی دکمه نخست، قابلیت مکان یابی دستگاه اندرویدی فعال شده و مختصات دریافتی و همچنین زمان آخرین بروزرسانی در TextView ها نمایش داده می‌شود. همچنین با کلیک روی دکمه دوم، قابلیت مکان یابی غیر فعال خواهد شد.
طبق مبحث آموزش ساخت پروژه در اندروید استودیو یک پروژه اندرویدی با نام Location می‌سازم. اکتیویتی را از نوع Empty Activity و زبان را Java انتخاب کردم.
در ابتدای مبحث عنوان شد که ابزار مورد استفاده ما یکی از Location API های Google Play services هست. بنابراین در قدم اول لازم است کتابخانه موردنیاز این API را به پروژه اضافه کنیم:

build.gradle(app)

apply plugin: 'com.android.application'

android {
    compileSdkVersion 30
    buildToolsVersion "30.0.0"

    defaultConfig {
        applicationId "ir.android_studio.location"
        minSdkVersion 19
        targetSdkVersion 30
        versionCode 1
        versionName "1.0"

        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar"])
    implementation 'androidx.appcompat:appcompat:1.1.0'
    implementation 'com.google.android.gms:play-services-location:17.0.0'
}

کتابخانه com.google.android.gms:play-services-location همانطور که از نامش پیداست برای استفاده از قابلیت location در Play services ساخته شده.
مسلما برنامه ما برای دریافت موقعیت مکانی، نیاز به دریافت مجوز حق دسترسی یا Permission مربوطه از سیستم عامل را دارد. قبلا در مبحث آموزش Runtime Permission در اندروید با انواع مجوزها آشنا شدیم. برای دسترسی برنامه به موقعیت مکانی، مجوز زیر را درون مانیفست پروژه تعریف می‌کنم:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

همچنین از آنجایی که قصد داریم از قابلیت مکان یابی در اندروید به واسطه API موجود در Google Play services دستگاه استفاده کنیم، باید مشخص شود برنامه با چه نسخه‌ای از ابزار Google Play services موجود در SDK اندروید استودیو ساخته شده است. تگ meta-data زیر را به بدنه تگ application مانیفست اضافه می‌کنیم:

<meta-data android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

در انتها، مانیفست پروژه به صورت زیر تکمیل می‌شود:

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="ir.android_studio.location">

    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />

        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

در مرحله بعد، آیتم‌های مورد نیاز در layout اکتیویتی را اضافه می‌کنم که شامل دو Button و سه TextView است:

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MainActivity">

    <Button
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="شروع مکان یابی"
        android:textSize="20dp"
        android:id="@+id/start_btn"
        android:onClick="startUpdatesButtonHandler"/>

    <Button
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="توقف مکان یابی"
        android:textSize="20dp"
        android:id="@+id/stop_btn"
        android:onClick="stopUpdatesButtonHandler"
        android:enabled="false"/>

    <TextView
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:id="@+id/latitude_txt"
        android:gravity="center"
        android:textSize="20dp" />

    <TextView
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:id="@+id/longitude_txt"
        android:gravity="center"
        android:textSize="20dp"/>

    <TextView
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:id="@+id/update_txt"
        android:gravity="center"
        android:textSize="20dp"/>

</LinearLayout>

دو ویژگی جدید به نام‌های onClick و enabled در دکمه‌ها استفاده شده. ویژگی اول برای تعریف متد مربوط به رویداد دکمه در اکتیویتی است که جایگزین setOnClickListener بشمار می‌رود. مورد دوم هم چنانچه با مقدار false تعریف شود، دکمه در حالت پیش فرض به صورت غیر فعال و غیر قابل کلیک ظاهر می‌شود.
کارکرد پروژه ما به اینصورت است که با کلیک روی دکمه اول، ابتدا بررسی می‌شود آیا پرمیشن Location قبلا به برنامه ما داده شده یا نه. بعد از دریافت مجوز دسترسی از کاربر، در صورتی که قابلیت مکان یابی دستگاه فعال بوده و موقعیت جغرافیایی آن در دسترس باشد، اطلاعات آن شامل Latitude (عرض جغرافیایی)، Longitude (طول جغرافیایی) و همچنین آخرین زمان دریافت آخرین موقعیت در قالب سه TextView نمایش داده می‌شود. قبلا در آموزش نمایش نقشه Google Map در برنامه اندرویدی با این اصطلاحات آشنا شدیم.
همچنین در صورت کلیک روی دکمه دوم، عملیات بروزرسانی موقعیت مکانی متوقف خواهد شد. البته چنانچه قابلیت مکان یابی فعال نباشد ابتدا یک دیالوگ به کاربر نمایش داده می‌شود و اعلام می‌کند این برنامه به فعال شدن Location نیاز دارد که با تایید آن توسط کاربر، این قابلیت فعال خواهد شد.
حالا نوبت به نوشتن کدهای back end اکتیویتی می‌رسد. در قدم اول، MainActivity پروژه را به صورت زیر تکمیل کردم که جزئیات را به مرور توضیح خواهم داد:

MainActivity.java

package ir.android_studio.location;

import androidx.appcompat.app.AppCompatActivity;

import android.location.Location;
import android.os.Bundle;
import android.widget.Button;
import android.widget.TextView;

import com.google.android.gms.location.FusedLocationProviderClient;
import com.google.android.gms.location.LocationCallback;
import com.google.android.gms.location.LocationRequest;
import com.google.android.gms.location.LocationSettingsRequest;
import com.google.android.gms.location.SettingsClient;

public class MainActivity extends AppCompatActivity {

    private Button startBtn, stopBtn;
    private TextView latitudeTxt, longitudeTxt, updateTimeTxt;

    private static final int REQUEST_PERMISSIONS_REQUEST_CODE = 2;
    private static final int REQUEST_CHECK_SETTINGS = 1;
    private static final long UPDATE_INTERVAL_IN_MILLISECONDS = 10000;
    private static final long FASTEST_UPDATE_INTERVAL_IN_MILLISECONDS = 5000;
    private final static String KEY_REQUESTING_LOCATION_UPDATES = "requesting-location-updates";
    private final static String KEY_LOCATION = "location";
    private final static String KEY_LAST_UPDATED_TIME_STRING = "last-updated-time-string";
    private Boolean requestingLocationUpdates;
    private String lastUpdateTime;

    private FusedLocationProviderClient mFusedLocationClient;
    private SettingsClient settingsClient;
    private LocationRequest locationRequest;
    private LocationSettingsRequest locationSettingsRequest;
    private LocationCallback locationCallback;
    private Location currentLocation;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        startBtn = findViewById(R.id.start_btn);
        stopBtn = findViewById(R.id.stop_btn);
        latitudeTxt = findViewById(R.id.latitude_txt);
        longitudeTxt = findViewById(R.id.longitude_txt);
        updateTimeTxt = findViewById(R.id.update_txt);

        requestingLocationUpdates = false;
        lastUpdateTime = "";

       mFusedLocationClient = LocationServices.getFusedLocationProviderClient(this);
       settingsClient = LocationServices.getSettingsClient(this);


    }
}

همانطور که ملاحظه می‌کنید ابتدا دکمه‌ و TextView ها را تعریف کرده‌ام.
همچنین چندین متغیر از جنس int، long، String و Boolean و در نهایت، از ۶ کلاس که مربوط به کتابخانه play-services-location هستند یک نمونه ساخته‌ام.
در ابتدا برای متغیر requestingLocationUpdates درون متد onCreate مقدار false تعریف کردم زیرا در حالت عادی و تا قبل از کلیک روی دکمه شروع مکان یابی نباید موقعیت مکانی دریافت و بروزرسانی شود. برای متغیری که جهت نمایش آخرین تاریخ بروزرسانی موقعیت تعریف شده هم یک رشته خالی به عنوان مقدار پیش فرض تعریف شده.
در پایان با استفاده از دو متد getFusedLocationProviderClient و getSettingsClient دو کلاس FusedLocationProviderClient و SettingsClient آماده استفاده در اکتیویتی شده‌اند.

ارسال درخواستِ دریافت موقعیت مکانی:

برای ارسال درخواست دریافت موقعیت مکانی به API و همچنین تعیین فاصله زمانی بروزرسانی آن، از کلاس LocationRequest استفاده می‌کنیم. یک متد با نام دلخواه createLocationRequest به اکتیویتی اضافه کرده و داخل آن را به صورت زیر تکمیل می‌کنم:

private void createLocationRequest() {

    locationRequest = new LocationRequest();
    locationRequest.setInterval(UPDATE_INTERVAL_IN_MILLISECONDS);
    locationRequest.setFastestInterval(FASTEST_UPDATE_INTERVAL_IN_MILLISECONDS);
    locationRequest.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);

}

در کد فوق ابتدا از کلاس LocationRequest یک نمونه با نام locationRequest ساخته شده. سپس ۳ متد از این کلاس تعریف و مقدار دهی شده است.
setInterval: به وسیله این متد، فاصله زمانی بروزرسانی موقعیت مکانی را تعیین می‌کنیم که بر حسب میلی ثانیه تعریف می‌شود. من برای متغیر UPDATE_INTERVAL_IN_MILLISECONDS که از جنس long تعریف شده، مقدار ۱۰۰۰۰ تعیین کردم بنابراین برنامه من هر ۱۰ ثانیه یکبار جدیدترین مختصات موقعیت مکانی را از سیستم عامل و به عبارت دیگر از Google Play services دریافت می‌کند.
setFastestInterval:: این متد، سریع‌ترین (Fastest) فاصله زمانی برای دریافت بروزرسانی موقعیت مکانی را تعیین می‌کند. کاربرد این متد این است که چنانچه در بازه زمانی کوتاهتری از آنچه قبلا در setInterval تعریف کردیم، موقعیت مکانی دستگاه به واسطه سایر برنامه‌های موجود روی دستگاه (مانند اپلیکیشن‌های مکان یاب و…) بروزرسانی شود، مختصات توسط برنامه ما نیز دریافت شده و ارسال درخواست بروزرسانی موقعیت مکانی از جانب برنامه ما به تعویق می‌افتد. این کار باعث کاهش تعداد درخواست‌های بروزرسانی از جانب برنامه‌های نصب شده روی دستگاه شده که در نهایت موجب صرفه جویی در مصرف باتری خواهد شد.
من برای این متد مقدار ۵۰۰۰ میلی ثانیه را تعیین کردم. بنابراین چنانچه بعد از آخرین درخواست بروزرسانی از جانب برنامه ما، یک درخواست بروزرسانی موقعیت مکانی در کمتر از مدت ۵ ثانیه از جانب برنامه دیگری به API ارسال شود، مختصات دریافتی توسط برنامه ما نیز دریافت شده و ارسال درخواست بعدی تا ۱۰ ثانیه دیگر به تعویق می‌افتد.
setPriority:: این متد همانطور که از نامش پیداست (Priority به معنی اولویت) اولویت درخواست مکان یابی ما را برای سیستم عامل مشخص می‌کند. این اولویت شامل نوع و دقت مکان یابی است که مشخص می‌کند در تعیین موقعیت از چه پارامترهایی استفاده و از چه آیتم‌های صرف نظر شود.

به عنوان مثال PRIORITY_HIGH_ACCURACY بیشترین دقت را در تعیین مکان بکار می‌گیرد که عمدتا از GPS برای تعیین موقعیت استفاده می‌شود و طبیعتا مصرف باتری نیز با افزایش همراه خواهد بود. اما در نوع دیگری مانند PRIORITY_BALANCED_POWER_ACCURACY عمدتا از اطلاعات دریافتی از شبکه WiFi و دکل‌های مخابراتی استفاده می‌شود که مصرف انرژی کمتری داشته و البته دقت آن نیز نسبت به GPS به مراتب پایین تر خواهد بود.
برای من دقت در اولویت است بنابراین PRIORITY_HIGH_ACCURACY را انتخاب کرده‌ام.

تعیین نوع سرویس‌های مکان یابی

در قسمت قبل، تنظیماتی که برای سرویس مکان یابی لازم بود را در locationRequest تعیین کردیم. برای ارسال این تنظیمات به API مکان یابی Google Play services باید از کلاس LocationSettingsRequest.Builder استفاده کنیم.
یک تابع جدید با نام دلخواه buildLocationSettingsRequest در اکتیویتی ایجاد کردم که به صورت زیر تکمیل شده:

private void buildLocationSettingsRequest() {

    LocationSettingsRequest.Builder lsrBuilder = new LocationSettingsRequest.Builder();
    lsrBuilder.addLocationRequest(locationRequest);
    locationSettingsRequest = lsrBuilder.build();

}

دریافت پاسخ موقعیت مکانی

درخواستی که در قسمت نخست و توسط کلاس LocationRequest به API ارسال شد، توسط کلاس LocationCallback دریافت می‌شود. یک متد دیگر با نام دلخواه createLocationCallback به اکتیویتی اضافه کرده و به صورت زیر تکمیل می‌کنم:

private void createLocationCallback() {

    locationCallback = new LocationCallback() {
        @Override
        public void onLocationResult(LocationResult locationResult) {
            super.onLocationResult(locationResult);
            
            currentLocation = locationResult.getLastLocation();
            lastUpdateTime = DateFormat.getTimeInstance().format(new Date());
            updateLocationUI();

        }
    };

}

ابتدا یک نمونه از کلاس LocationCallback ساخته‌ام. سپس متد onLocationResult را تعریف کرده‌ام:

این متد یک پارامتر از جنس LocationResult دارد که به صورت پیش فرض نام locationResult برای آن انتخاب شده است. این متد هنگامی فراخوانی می‌شود که موقعیت مکانی دستگاه در دسترس باشد.
داخل این متد، سه خط زیر اضافه شده:

currentLocation = locationResult.getLastLocation();
lastUpdateTime = DateFormat.getTimeInstance().format(new Date());
updateLocationUI();

currentLocation را قبلا داخل بدنه کلاس از جنس کلاس Location تعریف کردم. در اینجا آخرین موقعیت مکانی دستگاه توسط getLastLocation دریافت شده و در currentLocation ذخیره می‌شود.

در خط دوم، آخرین زمان بروزرسانی موقعیت مکانی در متغیر lastUpdateTime ذخیره می‌شود. عملیات بروزرسانی صفحه برنامه و نمایش مختصات جغرافیایی و همچنین تاریخ بروزرسانی را در یک متد مجزا انجام خواهیم داد که نام updateLocationUI را برای آن انتخاب کرده‌ام. در ادامه مبحث این متد را کامل خواهیم کرد.

تکمیل متد updateLocationUI

متد را به اینصورت تکمیل می‌کنم:

private void updateLocationUI() {

    if (currentLocation != null) {
        latitudeTxt.setText(String.format(Locale.ENGLISH,  "%s: %f", "عرض جغرافیایی", currentLocation.getLatitude()));
        longitudeTxt.setText(String.format(Locale.ENGLISH,  "%s: %f", "طول جغرافیایی", currentLocation.getLongitude()));
        updateTimeTxt.setText(String.format(Locale.ENGLISH,  "%s: %s", "آخرین بروزرسانی", lastUpdateTime));
    }

}

در اینجا بررسی می‌شود چنانچه currentLocation خالی نبود و به عبارتی، مختصات جغرافیایی را از API دریافت کرده باشد، به همراه زمان آخرین بروزرسانی موقعیت روی TextView های مربوطه نمایش داده شوند.

بروزرسانی داده‌های دریافتی روی صفحه

برای ذخیره و بروزرسانی مختصات و زمان آخرین بروزرسانی، ابتدا متد onSaveInstanceState را درون اکتیویتی اضافه کرده و تکمیل می‌کنم:

@Override
public void onSaveInstanceState(@NonNull Bundle outState, @NonNull PersistableBundle outPersistentState) {

    outState.putBoolean(KEY_REQUESTING_LOCATION_UPDATES, requestingLocationUpdates);
    outState.putParcelable(KEY_LOCATION, currentLocation);
    outState.putString(KEY_LAST_UPDATED_TIME_STRING, lastUpdateTime);

    super.onSaveInstanceState(outState, outPersistentState);
}

در خط اول، یک مقدار از جنس Boolean یعنی true یا false در Bundle ذخیره می‌شود که مشخص می‌کند آیا درخواست بروزرسانی موقعیت ارسال شده یا خیر. همچنین در خط دوم موقعیت فعلی و در خط سوم، زمان بروزرسانی ذخیره می‌شود.
حالا برای فراخوانی داده‌های ذخیره شده در قسمت قبل و ارسال آنها به رابط کاربری، یک متد دیگر با نام دلخواه updateValuesFromBundle به اکتیویتی اضافه می‌کنم. این تابع یک پارامتر از جنس Bundle دارد که نام savedState را برای آن انتخاب کرده‌ام:

private void updateValuesFromBundle(Bundle savedState) {

    if (savedState != null) {
        if (savedState.containsKey(KEY_REQUESTING_LOCATION_UPDATES)) {
            requestingLocationUpdates = savedState.getBoolean(KEY_REQUESTING_LOCATION_UPDATES);
        }
        if (savedState.containsKey(KEY_LOCATION)) {
            currentLocation = savedState.getParcelable(KEY_LOCATION);
        }
        if (savedState.containsKey(KEY_LAST_UPDATED_TIME_STRING)) {
            lastUpdateTime = savedState.getString(KEY_LAST_UPDATED_TIME_STRING);
        }
        
        updateUI();
        
    }

}

ابتدا بررسی شده چنانچه savedState خالی نباشد (یعنی قبلا داده‌هایی در Bundle ذخیره شده باشد) سایر شروط را اجرا کن.
قبلا در متد onSaveInstanceState داده‌ها را با سه کلید ذخیره کردیم. اینجا Bundle بررسی می‌شود و چنانچه کلیدها وجود داشتند؛ یعنی saveState.containsKey(KEY_NAME) خالی نبود، مقدار آن را در متغیر مربوطه قرار بده. لغت contains به معنی “شامل بودن” است.
در قسمت قبل، داده‌ها ذخیره (Put) و در این قسمت، دریافت (Get) شده‌اند.
در نهایت، بروزرسانی داده‌ها توسط متد updateUI انجام خواهد شد که در ادامه مبحث توضیح خواهم داد.

جهت مطالعه ادامه آموزش، فایل PDF را دانلود نمائید

توجه : سورس پروژه درون پوشه Exercises قرار دارد

با توجه به اینکه آموزش‌های پایه با قیمت پایین در اختیار کاربر قرار گرفته و درآمد حاصل صرف تامین هزینه‌های وب سایت و تهیه آموزش‌های آتی می‌شود، به اشتراک گذاری این فایل با دیگران خلاف اخلاق است.

نوشته مکان یابی در اندروید توسط GoogleApi اولین بار در اندروید استودیو پدیدار شد.

در جلسه گذشته به نحوه نمایش نقشه Google Maps در اندروید پرداختیم. به دلیل محدودیت‌هایی که به واسطه پرداخت ارزی جهت استفاده از API های گوگل مپ برای توسعه دهندگان و برنامه نویسان اندرویدی داخل ایران وجود دارد تصمیم گرفتیم نحوه کار با یکی از سرویس دهنده‌های نقشه ایرانی را آموزش دهیم. در این جلسه و جلسات بعد به آموزش استفاده از نقشه سیدار مپ (CedarMaps) در اندروید می‌پردازیم.

تصاویر نهایی پروژه:

این جلسه در قالب PDF و در ۶۹ صفحه تهیه شده که در ادامه چند صفحه‌ ابتدایی را مشاهده می‌کنید:

چرا سیدار مپ؟

اگر آموزش جلسه قبل را مطالعه کرده باشید گفتیم که مدتیست گوگل سیاست خود در قبال ارائه API های مرتبط با Google Map را تغییر داده و برای استفاده از پلن رایگان و محدود هم نیاز به احراز هویت از طریق Billing دارد که تهیه آن برای اکثر برنامه نویسان و توسعه دهندگان داخل ایران ممکن نیست. ضمن اینکه هر لحظه ممکن است تحریم‌های جدیدی روی این سرویس‌ها اعمال شده و به عنوان مثال حتی امکان استفاده رایگان از SDK نقشه هم وجود نداشته باشد. بنابراین انتخاب منطقی این است که از سایر گزینه‌های روی میز استفاده کنیم!
سرویس‌های داخلی متعددی در حال حاضر بر سر ارائه API نقشه به رقابت با یکدیگر پرداخته‌اند که می‌توان به سیدار مپ، نشان و مپ اشاره کرد. هرکدام از این سرویس‌ها SDK مربوط به اندروید را در اختیار توسعه دهندگان قرار داده‌اند که با اضافه کردن آن به پروژه می‌توان از API ها و قابلیت‌های مختلف از جمله نمایش موقعیت مکانی روی نقشه، مکان یابی، مسیریابی و تبدیل نقطه جغرافیایی به آدرس استفاده کرد.
هرکدام از این سرویس دهنده‌ها مزایا و معایبی داشته و علاوه بر آن در نحوه تعرفه گذاری نیز تفاوت‌هایی دارند.

تصویر فوق مربوط به تعرفه‌های سیدار مپ در زمان تهیه این آموزش است. پلن رایگان آن شامل ۲۰۰۰ API Call در روز است. یعنی تا ۲۰۰۰ درخواست از سمت کاربران برنامه ما بطور رایگان پاسخ داده می‌شود. این درخواست‌ها شامل نمایش موقعیت مکانی کاربر، تبدیل موقعیت جغرافیایی به آدرس (شامل استان، شهر، منطقه، خیابان، کوچه و…)، مسیریابی و تخمین مسافت خواهد بود که توسط کاربران برنامه ارسال می‌شود.
همچنین در پلن رایگان نمایش و لود نقشه تا سقف ۱۰۰۰۰ مرتبه در روز امکان پذیر است. بنابراین واضح است که صرف نمایش نقشه روی برنامه، یک API Call محسوب نمی‌شود و فقط مصرف پهنای باند را در پی خواهد داشت که در این پلن تا ۱۰۰ گیگابایت در ماه تعیین شده.
با توجه به مشخصات پلن رایگان CedarMap می‌توان گفت برای اکثر اپلیکیشن‌های با مخاطب کم، همین پلن کفایت کرده و حداقل برای ابتدای کار نیازی به ارتقاء به پلن‌های بالاتر و پرداخت هزینه نیست. برای استفاده از پلن رایگان باید درخواست خود را در قسمت مربوطه داخل سایت سیدار مپ ارسال کنید. معمولا در کمتر از ۲۴ ساعت اطلاعات مورد نیاز برای استفاده از نقشه به ایمیل شما ارسال خواهد شد. این اطلاعات شامل یک Client ID و Client Secret است که باید در پروژه تعریف شود.
اگر صفحه نخست وب سایت سیدار مپ را بررسی کرده باشید عمده تمرکز آن روی مقایسه نقشه گوگل و سیدار مپ است. از جمله خوانایی و زیبایی، سرعت، جزئیات نقشه، دقت بیشتر در مسیریابی و… که در تمام موارد برتری سیدار مپ نتیجه گرفته شده. البته که بنده تمام این برتری‌ها را تایید نمی‌کنم و در برخی موارد اغراق شده. حتی در تست‌ها مشخص شد در برخی موارد از جمله تبدیل موقعیت جغرافیایی به آدرس (بخصوص در مناطقی غیر از کلان شهرها) سیدار مپ از دقت کمتری برخوردار بوده و هنوز تا رسیدن به حد مطلوب جای کار دارد.

با اینحال از نظر بنده و در مقایسه‌ای که بین چند سرویس دهنده داخلی انجام دادم در نهایت این سرویس را انتخاب کردم.

پیاده سازی نقشه سیدار مپ در اپلیکیشن اندرویدی

در صفحه مستندات نقشه سیدار مپ اطلاعات مربوط به نحوه پیاده سازی نقشه و API های آن در اندروید، iOS و وب در دسترس توسعه دهندگان قرار گرفته است:

با کلیک روی گزینه Android به صفحه SDK سیدار مپ برای پلتفرم اندروید در گیت هاب منتقل می‌شوم:

https://github.com/cedarstudios/cedarmaps-android-sdk

در این صفحه توضیحاتی در خصوص نحوه اضافه کردن کتابخانه SDK سیدار مپ به پروژه اندرویدی در اندروید استودیو توضیحاتی ارائه شده. همچنین به این نکته اشاره شده که SDK سیدار مپ بر پایه SDK مپ باکس (MapBox) ساخته شده و امکاناتی به آن اضافه شده است. MapBox خود یک سرویس دهنده نقشه جایگزین گوگل مپ بوده که البته برخلاف سیدار مپ ایرانی نیست.
بیشتر از این درگیر مباحث تئوری نشده و در ادامه آموزش به نحوه کار با نقشه سیدار مپ در اندروید استودیو می‌پردازم.

ساخت پروژه اندرویدی سیدار مپ

در این پروژه قصد داریم در قالب چند فرگمنت، امکانات و API های مختلف نقشه سیدار مپ را آموزش دهیم. طبق آموزش ساخت پروژه در اندروید استودیو یک پروژه با نام CedarMap با یک Empty Activity و زبان Java ایجاد می‌کنم.
ابتدا مطابق توضیحات موجود در صفحه گیت هاب سیدار مپ اندروید، هردو فایل build.gradle سطح project و app را ویرایش می‌کنم. در قدم نخست و در build.gradle سطح پروژه، آدرس مخزن سیدار مپ را در بلاک repositories زیرمجموعه بلاک allprojects اضافه می‌کنم:

build.gradle (Project)

buildscript {
    repositories {
        google()
        jcenter()
        
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.3'
        
    }
}

allprojects {
    repositories {
        jcenter()
        google()

        maven {
            url "https://repo.cedarmaps.com/android/"
        }
        
    }
}

task clean(type: Delete) {
    delete rootProject.buildDir
}

در قدم بعد فایل build.gradle سطح app را ویرایش می‌کنم. برای جلوگیری از بروز خطای مربوط به نسخه جاوا، مطابق توضیحات موجود در صفحه گیت هاب سیدار مپ یک بلاک با نام compileOptions به بلاک android باید اضافه شود:

build.gradle (app)

android {
    compileSdkVersion 29
    buildToolsVersion "29.0.3"
    defaultConfig {
        applicationId "ir.android_studio.cedarmap"
        minSdkVersion 19
        targetSdkVersion 29
        versionCode 1
        versionName "1.0"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

در ادامه کتابخانه‌های مورد نیاز برای نقشه را در بلاک dependencies اضافه و پروژه را سینک می‌کنم:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'androidx.appcompat:appcompat:1.1.0'
    implementation 'com.cedarmaps:CedarMapsSDK:4.2.1'
    implementation 'com.mapbox.mapboxsdk:mapbox-android-plugin-annotation-v7:0.6.0'
    implementation 'com.google.android.material:material:1.2.0-alpha04'
    implementation 'androidx.vectordrawable:vectordrawable:1.1.0'
}

کتابخانه اصلی و ضروری سیدار مپ مورد اول یعنی CedarMapsSDK است که مربوط به SDK نقشه می‌باشد. ۳ مورد دیگر به ترتیب برای استفاده از سایر امکانات SDK مپ باکس، اضافه کردن دکمه FAB و Bottom Navigation و ترسیم تصاویر وکتوری تعریف شده‌اند.

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'androidx.appcompat:appcompat:1.1.0'
    implementation files('libs/CedarMapsSDK-4.2.1.aar')
    api 'com.mapbox.mapboxsdk:mapbox-android-sdk:8.4.0'
    implementation 'com.squareup.okhttp3:okhttp:3.12.6'
    implementation 'com.google.code.gson:gson:2.8.6'
    implementation 'com.mapbox.mapboxsdk:mapbox-android-plugin-annotation-v7:0.6.0'
    implementation 'com.google.android.material:material:1.2.0-alpha04'
    implementation 'androidx.vectordrawable:vectordrawable:1.1.0'
}

در مرحله بعد باید دسترسی‌های مورد نیاز نقشه سیدار مپ را در مانیفست پروژه تعریف کنیم که در مطلب پیاده سازی Runtime Permission در اندروید به طور مفصل با پرمیشن‌ها آشنا شدیم.

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="ir.android_studio.cedarmap">

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

دو مجوز دسترسی به اینترنت و موقعیت مکانی در مانیفست تعریف شد. در صورتی که بخواهیم مانند جلسه قبل صرفا یک موقعیت جغرافیایی از پیش تعیین شده را روی نقشه نشان دهیم مجوز دسترسی به اینترنت برای دریافت تایل‌های نقشه و نمایش آنها کفایت می‌کند. اما ما به دریافت موقعیت فعلی کاربر هم نیاز داریم.

در توضیحات صفحه گیت هاب قید شده که ClientID و ClientSecret بهتر است در یک subclass از کلاس Application پروژه تعریف شود. بنابراین یک کلاس با نام دلخواه CedarID به پروژه اضافه کرده و آنرا از کلاس Application ارث بری می‌کنم. سپس متد onCreate() را به کلاس اضافه و کد مربوطه را درون متد قرار می‌دهم:

CedarID.java

package ir.android_studio.cedarmap;

import android.app.Application;

import com.cedarstudios.cedarmapssdk.CedarMaps;
import com.cedarstudios.cedarmapssdk.model.MapID;

public class CedarID extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        CedarMaps.getInstance()
                .setClientID("YOUR_CLIENT_ID")
                .setClientSecret("YOUR_CLIENT_SECRET")
                .setContext(this)
                .setMapID(MapID.MIX);
    }
    
}

کافیست در کد فوق، دو کد دریافتی از سیدار مپ را جایگزین کنید. توجه داشته باشید subclass کلاس Application باید درون مانیفست تعریف شود. برای اینکار کافیست ویژگی name به تگ application مانیفست اضافه شود که مقدار آن، نام کلاس است:

<application
    android:name=".CedarID"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:supportsRtl="true"
    android:theme="@style/AppTheme">
    <activity android:name=".MainActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />

            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>

در layout اکتیویتی یک FrameLayout برای نمایش فرگمنت‌ها و یک BottomNavigationView‌ برای نمایش منوی پایین صفحه تعریف می‌کنم:

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MainActivity">

    <FrameLayout
        android:id="@+id/content"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="1">

    </FrameLayout>

    <com.google.android.material.bottomnavigation.BottomNavigationView
        android:id="@+id/navigationView"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_gravity="bottom"
        android:background="?android:attr/windowBackground"
        app:labelVisibilityMode="labeled"
        app:menu="@menu/navigation" />

</LinearLayout>

منوی BottomNavigation شامل ۴ آیتم است که با نام navigation.xml و در قالب یک menu در پروژه تعریف شده:

navigation.xml

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">

    <item
        android:id="@+id/navigation_map"
        android:icon="@drawable/ic_map_marker"
        android:title="نقشه" />

    <item
        android:id="@+id/navigation_reverse"
        android:icon="@drawable/ic_reverse_geocode"
        android:title="نقطه یابی" />

    <item
        android:id="@+id/navigation_forward"
        android:icon="@drawable/ic_forward_geocode"
        android:title="جستجو" />

    <item
        android:id="@+id/navigation_direction"
        android:icon="@drawable/ic_direction"
        android:title="مسیریابی" />

</menu>

حالا در اکتیویتی کدهای لازم را اضافه می‌کنم:

package ir.android_studio.cedarmap;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.material.bottomnavigation.BottomNavigationView;


public class MainActivity extends AppCompatActivity implements BottomNavigationView.OnNavigationItemSelectedListener {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    }
}

ابتدا کلاس اکتیویتی را implement می‌کنم به BottomNavigationView.OnNavigationItemSelectedListener. سپس با قرار دادن نشانگر موس روی بدنه کلاس و زدن alt + enter متد onNavigationItemSelected را به کلاس اضافه می‌کنم:

MainActivity.java

package ir.android_studio.cedarmap;

import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;
import android.view.MenuItem;

import com.google.android.material.bottomnavigation.BottomNavigationView;
import com.mapbox.mapboxsdk.geometry.LatLng;


public class MainActivity extends AppCompatActivity implements BottomNavigationView.OnNavigationItemSelectedListener {

    public static final LatLng VANAK_SQUARE = new LatLng(35.7572, 51.4099);
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        BottomNavigationView navigation = findViewById(R.id.navigationView);
        navigation.setOnNavigationItemSelectedListener(MainActivity.this);
        navigation.setSelectedItemId(R.id.navigation_map);

    }

    @Override
    public boolean onNavigationItemSelected(@NonNull MenuItem item) {
        return false;
    }
}

یک LatLng با نام VANAK_SQUARE تعریف شده که مختصات میدان ونک تهران در آن ذخیره شده. از این نقطه برای نمایش محل پیش فرض نقشه استفاده خواهیم کرد.
درون متد onCreate() اکتیویتی ویجت BottomNavigation را تعریف کرده و همچنین مشخص کردم آیتم با شناسه navigation_map به صورت پیش فرض و هنگام اجرای اپلیکیشن انتخاب شده باشد که مربوط به فرگمنت نمایش نقشه و موقعیت مکانی فرد خواهد بود.
متد onNavigationItemSelected را به صورت زیر تکمیل می‌کنم:

@Override
public boolean onNavigationItemSelected(@NonNull MenuItem item) {
    Fragment fragment = null;
    switch (item.getItemId()) {
        case R.id.navigation_map:
            setTitle("نقشه");
            fragment = new MapFragment();
            break;
        case R.id.navigation_reverse:
            setTitle("نقطه یابی");
            fragment = new ReverseGeocodeFragment();
            break;
        case R.id.navigation_forward:
            setTitle("");
            fragment = new ForwardGeocodeFragment();
            break;
        case R.id.navigation_direction:
            setTitle("مسیریابی");
            fragment = new DirectionFragment();
            break;
    }

    if (fragment != null) {
        FragmentTransaction transaction = getSupportFragmentManager().beginTransaction();
        if (getSupportFragmentManager().getFragments().isEmpty()) {
            transaction.add(R.id.content, fragment, String.format(Locale.US, "item: %d", item.getItemId())).commit();
        } else {
            transaction.replace(R.id.content, fragment, String.format(Locale.US, "item: %d", item.getItemId())).commit();
            invalidateOptionsMenu();
        }
        return true;
    }

    return false;
}

با لمس هریک از آیتم‌های منو، فرگمنت مربوطه اجرا خواهد شد.
دسترسی به موقعیت جغرافیایی کاربر جزء مجوزهای خطرناک (Dangerous Permissions) بحساب می‌آید بنابراین طبق مبحث Runtime Permission باید برای اندروید ۶ و به بالا هنگام اجرای برنامه مجوز مربوطه را از کاربر دریافت کنیم. برای اینکار متد onRequestPermissionsResult را در کلاس اکتیویتی Override می‌کنم:
@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
}

متد را به صورت زیر تکمیل می‌کنم:

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {

    List allFragments = getSupportFragmentManager().getFragments();
    if (allFragments.isEmpty()) {
        return;
    }

    Fragment currentFragment = (Fragment) allFragments.get(allFragments.size() - 1);
    if (currentFragment instanceof PermissionsListener) {
        currentFragment.onRequestPermissionsResult(requestCode, permissions, grantResults);
        return;
    }

    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
}

ابتدا بررسی می‌شود آیا فرگمنتی وجود دارد یا نه. در صورتی که جواب منفی بود (یعنی allFragments برابر با isEmpty باشد) هیچ کاری انجام نشده و return می‌شود. در ادامه شرطی را تعریف می‌کنم تا صرفا هنگامی مجوز دسترسی به موقعیت مکانی از کاربر دریافت شود که به آن نیاز داشته باشیم. به عنوان مثال در API جستجو بر اساس نام مکان و یا مسیریابی، نیازی به موقعیت کاربر نیست و چنانچه شخص صرفا از این قابلیت استفاده کند منطقی نیست دسترسی موقعیت را درخواست کنیم.
ابتدا فرگمنت در حال اجرا در currentFragment قرار می‌گیرد. سپس بررسی می‌کنیم اگر از فرگمنت موجود در currentFragment درخواست مجوز دسترسی ارسال شده، پیغام مربوطه را به کاربر نمایش بده تا دسترسی را تایید یا لغو کند. در اینجا خبری از کدهای طولانی Runtime Permission پیش فرض اندروید نیست و مدیریت اینکار توسط اینترفیس PermissionsListener انجام می‌شود که مربوط به MapBox است. در واقع MapBox توسعه دهنده را از نوشتن کدهای اضافی بی نیاز کرده. البته استفاده از این قابلیت مپ باکس الزامی نبوده و می‌توان به صورت عادی و طبق آنچه در مبحث مربوط به Runtime Permission تمرین کرده بودیم مجوز دسترسی به موقعیت جغرافیایی را هنگام اجرای برنامه یا هنگام اجرای فرگمنت مدنظر از کاربر دریافت کنیم.

if (currentFragment instanceof PermissionsListener)

در خط فوق بررسی می‌شود آیا فرگمنت ذخیره شده در متغیر currentFragment از جنس PermissionsListener هست یا نه. به عبارت دیگر بررسی می‌شود آیا در فرگمنت فعلی مجوزی نیاز هست که مربوط به MapBox باشد یا خیر. به طور خلاصه دستور instanceof در جاوا وظیفه برگرداندن نتیجه مقایسه جنس دو آیتم را بر عهده دارد.
کد نهایی اکتیویتی:

MainActivity.java

package ir.android_studio.cedarmap;

import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.fragment.app.Fragment;
import androidx.fragment.app.FragmentTransaction;

import android.os.Bundle;
import android.view.MenuItem;

import com.google.android.material.bottomnavigation.BottomNavigationView;
import com.mapbox.android.core.permissions.PermissionsListener;
import com.mapbox.mapboxsdk.geometry.LatLng;

import java.util.List;
import java.util.Locale;


public class MainActivity extends AppCompatActivity implements BottomNavigationView.OnNavigationItemSelectedListener {

    public static final LatLng VANAK_SQUARE = new LatLng(35.7572, 51.4099);

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        BottomNavigationView navigation = findViewById(R.id.navigationView);
        navigation.setOnNavigationItemSelectedListener(MainActivity.this);
        navigation.setSelectedItemId(R.id.navigation_map);

    }

    @Override
    public boolean onNavigationItemSelected(@NonNull MenuItem item) {
        Fragment fragment = null;
        switch (item.getItemId()) {
            case R.id.navigation_map:
                setTitle("نقشه");
                fragment = new MapFragment();
                break;
            case R.id.navigation_reverse:
                setTitle("نقطه یابی");
                fragment = new ReverseGeocodeFragment();
                break;
            case R.id.navigation_forward:
                setTitle("");
                fragment = new ForwardGeocodeFragment();
                break;
            case R.id.navigation_direction:
                setTitle("مسیریابی");
                fragment = new DirectionFragment();
                break;
        }

        if (fragment != null) {
            FragmentTransaction transaction = getSupportFragmentManager().beginTransaction();
            if (getSupportFragmentManager().getFragments().isEmpty()) {
                transaction.add(R.id.content, fragment, String.format(Locale.US, "item: %d", item.getItemId())).commit();
            } else {
                transaction.replace(R.id.content, fragment, String.format(Locale.US, "item: %d", item.getItemId())).commit();
                invalidateOptionsMenu();
            }
            return true;
        }

        return false;
    }

    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {

        List allFragments = getSupportFragmentManager().getFragments();
        if (allFragments.isEmpty()) {
            return;
        }

        Fragment currentFragment = (Fragment) allFragments.get(allFragments.size() - 1);
        if (currentFragment instanceof PermissionsListener) {
            currentFragment.onRequestPermissionsResult(requestCode, permissions, grantResults);
            return;
        }

        super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    }

}

جهت مطالعه ادامه آموزش، فایل PDF را دانلود نمائید

توجه : سورس پروژه درون پوشه Exercises قرار دارد

با توجه به اینکه آموزش‌های پایه با قیمت پایین در اختیار کاربر قرار گرفته و درآمد حاصل صرف تامین هزینه‌های وب سایت و تهیه آموزش‌های آتی می‌شود، به اشتراک گذاری این فایل با دیگران خلاف اخلاق است.

نوشته نقشه سیدار مپ و API های آن اولین بار در اندروید استودیو پدیدار شد.

امکانات نقشه Google Map اندروید

به نام خدا. نقشه گوگل مپ امکانات و قابلیت‌های متعددی را در اختیار توسعه دهندگان و برنامه نویسان اندرویدی و سایر پلتفرم‌ها قرار داده است. از جمله این قابلیت‌ها می‌توان به نمایش نقشه جهان، نمایش موقعیت مکانی شخص، جستجو بر اساس نام اماکن و شهرها، مسیریابی، نمایش اطلاعات اماکن، نمایش نقشه ماهواره‌ای و… اشاره کرد.
متاسفانه مدتیست گوگل سیاست خود در نحوه ارائه API نقشه را تغییر داده و مانند قبل امکان استفاده رایگان از این سرویس وجود ندارد. البته گوگل یک پلن رایگان و به صورت محدود ارائه داده که برای هریک از قابلیت‌های نقشه، تعداد درخواست معینی را در یک ماه می‌توان ارسال کرد. با اینحال فعالسازی این پلن رایگان هم نیاز به ارائه مشخصات کارت بانکی یا به اصطلاح Billing دارد که برای برنامه نویسان داخل ایران خبر خوبی نیست!

البته صرفا نمایش نقشه برای سیستم عامل‌های موبایل بدون ثبت اطلاعات بانکی هم امکان پذیر است. بنابراین در صورتی که به سایر امکانات نقشه مانند جستجو و مسیریابی نیازی نداشته و هدف صرفا نمایش یک موقعیت مکانی روی نقشه باشد، گوگل مپ گزینه مناسبی است.
در این جلسه ابتدا در Console گوگل یک API برای نمایش نقشه فعال کرده سپس با استفاده از کلید API، نقشه Google Map در اندروید را پیاده سازی می‌کنیم.

ساخت API Key در Google Console

برای استفاده از API نقشه گوگل ابتدا با یک اکانت گوگل وارد لینک زیر می‌شویم:

https://console.developers.google.com

خدمات گوگل بر روی IP ایران محدود بوده و لازم است آی‌پی خود را تغییر دهیم. توصیه می‌کنم مطلب دور زدن تحریم‌های نرم افزاری را مطالعه کنید.

روی Select a project و سپس NEW PROJECT کلیک می‌کنم:

در اینجا یک نام برای پروژه تعریف می‌کنم. با کلیک روی دکمه CREATE پروژه ساخته می‌شود. سپس در قسمت Credentials روی دکمه Create credentials کلیک کرده و گزینه API key را انتخاب می‌کنم:

بلافاصله یک کلید ساخته می‌شود. این کلید را می‌توان محدود به یک محیط خاص (اپلیکیشن، وب و…) کرد. یعنی با محدود کردن این کلید به اپلیکیشن، در وب سایت قابل استفاده نخواهد بود و بلعکس. این گزینه برای من اهمیتی ندارد بنابراین با RESTRICT KEY کاری ندارم.
حالا در قسمت Dashboard پروژه روی دکمه ENABLE APIS AND SERVICES کلیک کرده و در مرحله بعد گزینه Maps SDK for Android را انتخاب و فعال می‌کنم:

فعلا با کنسول کاری نداریم.

ساخت پروژه نمایش نقشه Google Map در اپلیکیشن اندروید

در این پروژه قصد دارم یک موقعیت مکانی را به وسیله یک Marker نمایش دهم. طبق آموزش ساخت پروژه در اندروید استودیو یک پروژه با نام Google Map می‌سازم. اکتیویتی را از نوع Empty Activity و زبان را Java انتخاب کردم. البته بجای Empty Activity از یک Google Maps Activity می‌توان استفاده کرد که کار را ساده تر می‌کند. با اینحال می‌خواهم جزئیات را بررسی کنم و بهتر است که یک اکتیویتی معمولی را تکمیل کنیم.
برای استفاده از API نقشه گوگل مپ در اندروید نیاز به ابزار Google Play Services در SDK داریم. بنابراین قبل از هر چیز ابتدا SDK Manager را بررسی کنید و در صورت عدم نصب این ابزار، نصب را انجام دهید:

سپس باید کتابخانه play-services-maps که زیرمجموعه کتابخانه play-services هست را به پروژه اضافه کنیم.

نکته: استفاده از خود کتابخانه play-services به این دلیل که شامل چندین کتابخانه فرعی است توصیه نمی‌شود و صرفا کتابخانه‌های مورد نیاز پروژه را باید تعریف کرد. به این ترتیب از افزایش حجم برنامه جلوگیری می‌شود.

در مسیر File > Project Structure طبق تصویر زیر کتابخانه play-services-maps را در مخزن آنلاین کتابخانه‌های اندروید جستجو کرده و آخرین نسخه موجود را به پروژه اضافه می‌کنم:

کتابخانه به بلاک dependencies فایل build.gradle اضافه شد:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'androidx.appcompat:appcompat:1.1.0'
    implementation 'com.google.android.gms:play-services-maps:17.0.0'
}

نقشه به صورت آنلاین دریافت می‌شود بنابراین باید مجوز دسترسی به اینترنت را در مانیفست پروژه تعریف کنم:

<uses-permission android:name="android.permission.INTERNET" />

همچنین یک تگ meta-data لازم است در تگ application مانیفست تعریف شود که شامل دو ویژگی name و value است:

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_API_KEY" />

برای name مقدار com.google.android.geo.API_KEY و برای value کلیدی که در کنسول گوگل ساخته بودیم را قرار می‌دهیم. با اضافه شدن این تگ در مانفیست، گوگل بررسی می‌کند کلید تعریف شده قبلا در کنسول ایجاد شده باشد در غیر اینصورت نقشه لود نخواهد شد.

مانیفست به اینصورت تکمیل شد:

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="ir.android_studio.googlemap">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="AIzaSyAciVULMAzZmraF4UZ8b1ldfHZ6xK3DNGs" />

        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

در قدم بعد یک Fragment در layout اکتیویتی به صورت زیر تعریف می‌کنم. قبلا در مطلب آموزش کار با فرگمنت در اندروید با Fragment آشنا شدیم.

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map_fragment"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity" />

به ویژگی یا attribute هایی که برای فرگمنت تعریف شده دقت کنید. مقدار name باید همان چیزی باشد که در کد بالا مشاهده می‌کنید. همچنین در این اکتیویتی از Layout دیگری استفاده نشده بنابراین ویژگی context درون خود فرگمنت تعریف شده است.
حالا نوبت کدهای اکتیویتی ست. ابتدا باید interface ای با نام OnMapReadyCallback را روی کلاس اکتیویتی implement کنم. اگر به نام این اینترفیس دقت کنید احتمالا کاربرد آنرا خواهید فهمید. یک CallBack (پاسخ) برای هنگامی که نقشه (Map) آماده (Ready) نمایش باشد. عملکرد آن به اینصورت است که بررسی می‌کند چنانچه Google Play Services روی دیوایس کاربر (موبایل، تبلت، گجت‌های پوشیدنی) نصب نباشد پیغامی نمایش داده می‌شود با این مضمون که برای اجرای این بخش از برنامه (یعنی نمایش نقشه) باید Google Play Services نصب شود. پس از نصب، کاربر به برنامه برمی‌گردد. اما در صورتی که Google Play Services از قبل روی دیوایس نصب شده باشد، متد و کدهای مربوط به نقشه را فراخوانی می‌کند.

متد این اینترفیس را باید به اکتیویتی اضافه کنیم. روی آن alt + enter می‌زنم:

متد onMapReady() را انتخاب می‌کنم. اکتیویتی به صورت زیر تکمیل می‌شود:

MainActivity.java

package ir.android_studio.googlemap;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;

import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;

public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    }


    @Override
    public void onMapReady(GoogleMap googleMap) {
        
    }
}

ابتدا متدهای onCreate() و onMapReady() را تکمیل کرده سپس توضیحات لازم را بیان می‌کنم:

package ir.android_studio.googlemap;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;

import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap gMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map_fragment);
        mapFragment.getMapAsync(this);

    }


    @Override
    public void onMapReady(GoogleMap googleMap) {

        gMap = googleMap;
        LatLng myLocation = new LatLng(34.016774, 58.168308);
        gMap.addMarker(new MarkerOptions().position(myLocation).title("فردوس")).snippet("خراسان جنوبی"));
        gMap.moveCamera(CameraUpdateFactory.newLatLng(myLocation));

    }
}

برای نمایش نقشه Google Map در اندروید از SupportMapFragment استفاده می‌کنیم. یک نمونه (شیء) از این متد با نام mapFragment در onCreate() تعریف کردم. در خط بعد و توسط متد getMapAsync() زمانی که نقشه آماده نمایش باشد آنرا به mapFragment پاس می‌دهد. یعنی زمانی که OnMapReadyCallback اعلام کند نقشه آماده نمایش است.
در متد onMapReady() جزئیات مربوط به نقشه تعریف شده است. در کلاس اکتیویتی ابتدا یک نمونه از کلاس GoogleMap با نام gMap و سپس در onMapReady() تعریف شده است. برای تعیین موقعیت مکانی مدنظر از کلاس LatLng استفاده می‌شود. یک نمونه از آن با نام myLocation تعریف کردم. این کلاس دو ورودی می‌گیرد. ورودی اول Latitude (عرض جغرافیایی) و دومی Longitude (طول جغرافیایی):

LatLng myLocation = new LatLng(34.016774, 58.168308);

اگر با نقشه‌هایی مانند گوگل مپ کار کرده‌اید احتمالا این دو اصطلاح برایتان آشنا بنظر می‌رسد. برای تعیین یک موقعیت مکانی نیاز به طول و عرض جغرافیایی آن نقطه داریم. در نسخه وب Google Maps یا برنامه موبایلی Maps روی هر نقطه‌ای که کلیک کنید این دو عدد را نشان می‌دهد. اولی latitude و دومی longitude است. این دو عدد را به ترتیب در ورودی LatLng() قرار می‌دهم تا همان نقطه روی نقشه نشان داده شود:

در خط بعد، از addMarker برای نمایش محل دقیق موقعیت مکانی استفاده شده. Marker یک نشانه است که روی نقشه، محل مدنظر را به کاربر نشان می‌دهد. همچنین می‌توان اطلاعات و جزئیاتی از آن نقطه را نیز به مارکر اضافه کرد:

gMap.addMarker(new MarkerOptions().position(myLocation).title("فردوس")).snippet("خراسان جنوبی"));

توسط position() موقعیت و title() و snippet() نام و توضیحات محل موردنظر تعیین می‌شود. موقعیت از myLocation گرفته شده.
در نهایت با استفاده از moveCamera() قسمتی از نقشه روی صفحه نمایش قرار می‌گیرد که نقطه مدنظر ما در وسط آن (از هردو سمت افقی و عمودی) قرار دارد. در صورتی که این کلاس تعریف نشود، نقشه در محدوده پیش فرض گوگل مپ نمایش داده خواهد شد و کاربر برای پیدا کردن Marker باید به صورت دستی نقشه را جابجا کند.
پروژه را اجرا می‌کنم:

آیکون مارکر را مشاهده می‌کنید که درست در وسط صفحه قرار گرفته و نقطه‌ای که مختصات آن را تعیین کرده بودیم را نشان می‌دهد. اما چنانچه قصد داریم کاربر محل دقیق مدنظر را از فاصله‌ی نزدیکتر مشاهده کند لازم است نقشه در حالت زوم شده قرار گیرد:

gMap.moveCamera(CameraUpdateFactory.newLatLngZoom(myLocation, 15.5f));

بجای newLatLang از newLatLangZoom استفاده کردم. این متد علاوه بر گرفتن مختصات نقطه، یک عدد float (شناور) را می‌گیرد که میزان زوم نقشه را مشخص می‌کند. این عدد باید بین ۲٫۰ تا ۲۱٫۰ باشد. در خط بالا من مقدار ۱۵٫۵ تعیین کردم. اعداد float با اضافه شدن حرف f در انتهای عدد مشخص می‌شوند. پروژه را دوباره اجرا می‌کنم:

با کلیک یا ضربه روی آیکون مارکر، توضیحات محل نمایش داده می‌شود:

همچنین آیکون مارکر نیز قابل تغییر است:

gMap.addMarker(new MarkerOptions().position(myLocation).title("فردوس").snippet("خراسان جنوبی").icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));

امکانات بسیار زیادی در API گوگل مپ در اختیار داریم اما بنا به دلایلی که در ابتدای مبحث ذکر شد و محدودیت‌هایی که پیش روی ماست، صرفا به تعداد محدودی از قابلیت‌های موجود در همین API نقشه Google Map در اندروید اشاره و از معرفی سایر API ها و امکانات آن شامل Geocoder و… صرف نظر می‌کنم.
۱: نوع نقشه: همانطور که در نسخه تحت وب گوگل مپ یا اپلیکیشن آن، امکان نمایش نقشه در چند حالت مختلف (Normal، Satellite، Hybrid) وجود دارد، در API هم می‌توان هرکدام از این حالت‌ها را از گوگل دریافت و روی اپلیکیشن نمایش داد. اینکار توسط متد setMapType() انجام می‌شود:

gMap.setMapType(GoogleMap.MAP_TYPE_SATELLITE);

خط فوق را به متد onMapReady() اضافه کردم:

با تعریف MAP_TYPE_SATELLITE نقشه در حالت تصاویر ماهواره‌ای لود می‌شود. واژه Satellite به معنی ماهواره است. سایر آیتم‌ها را در لیست زیر مشاهده می‌کنید:

MAP_TYPE_NORMAL : همان نقشه پیش فرض را نمایش می‌دهد که شامل نام خیابانها، اماکن و… هست:

MAP_TYPE_TERRAIN: داده‌های توپوگرافی را نمایش می‌دهد:

MAP_TYPE_HYBRID: ترکیبی از حالت‌های NORMAL و SATELLITE است به این صورت که نام خیابانها، اماکن و سایر جزئیات بر روی تصاویر ماهواره‌ای نمایش داده می‌شود:

Map_TYPE_NONE: همان نقشه NORMAL را نمایش می‌دهد اما با جزئیاتی کمتر:

۲: دکمه‌های زوم: توسط متد setZoomControlsEnabled() می‌توانیم دکمه‌های +/- را به نقشه اضافه کنیم که در اینصورت کاربر امکان کنترل میزان زوم نقشه را دارد:

gMap.getUiSettings().setZoomControlsEnabled(true);

همچنین با تعریف کردن متد setZoomGesturesEnabled() علاوه بر دکمه‌های +/- عمل افزایش و کاهش زوم به ترتیب توسط “دو ضربه” روی صفحه نمایش و “یک ضربه با دو انگشت” روی صفحه نمایش انجام خواهد شد.
کد نهایی اکتیویتی:

MainActivity.java

package ir.android_studio.googlemap;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;

import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.BitmapDescriptorFactory;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap gMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map_fragment);
        mapFragment.getMapAsync(this);

    }


    @Override
    public void onMapReady(GoogleMap googleMap) {

        gMap = googleMap;
        gMap.setMapType(GoogleMap.MAP_TYPE_HYBRID);
        LatLng myLocation = new LatLng(34.016774, 58.168308);
        gMap.addMarker(new MarkerOptions().position(myLocation).title("فردوس").snippet("خراسان جنوبی")
                .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));
        //gMap.moveCamera(CameraUpdateFactory.newLatLng(myLocation));
        gMap.moveCamera(CameraUpdateFactory.newLatLngZoom(myLocation, 15.5f));
        gMap.getUiSettings().setZoomControlsEnabled(true);
        gMap.getUiSettings().setZoomGesturesEnabled(true);

    }
}

ساخت API Key جدید برای اپ release شده

کلیدی که ابتدای کار در کنسول ایجاد کردیم صرفا در حالت دیباگ پروژه از طرف گوگل تایید می‌شود و برای ساخت (release) کردن اپلیکیشن لازم است SHA-1 certificate fingerprint مربوط به امضای برنامه (Key store) را به همراه نام پکیج برنامه در کنسول تعریف کنیم. در مبحث آموزش ساخت فایل APK با نحوه ایجاد فایل امضاء آشنا شدیم.
برای بدست آوردن کد SHA-1 از ابزار keytool در JDK استفاده می‌کنیم. تفاوتی نمی‌کند خودتان یک نسخه از JDK را روی سیستم عامل نصب کرده‌اید یا از JDK داخلی و پیش فرض اندروید استودیو استفاده می‌کنید. در هرصورت در محل نصب JDK یک پوشه با نام bin وجود دارد که ابزار ازجمله keytool درون آن قرار داده شده. اگر JDK کاستوم نصب نکرده‌اید، نسخه داخلی اندروید استودیو در محل نصب اندروید استودیو و در پوشه jre قرار دارد:

Keytool درون پوشه bin پوشه jre قرار دارد بنابراین در سیستم عامل من آدرس این پوشه به اینصورت است:

C:\Program Files\Android\Android Studio1\jre\bin

داخل این پوشه با کلیدهای shift + right click گزینه open commant prompt (در ویندوز) را انتخاب می‌کنم تا cmd در این فولدر اجرا شود. یا اگر این گزینه در ویندوز فعال نیست، از منوی استارت cmd را اجرا کرده و با دستور زیر به این فولدر می‌روم:

cd C:\Program Files\Android\Android Studio1\jre\bin

سپس دستور زیر را اجرا می‌کنم:

keytool -list -v -keystore "KEYSTORE_PATH"

در KEYSTORE_PATH محلی که فایل کلید امضاء (.jks) قرار گرفته را جایگزین می‌کنم. برای مثال:

keytool -list -v -keystore "C:\MyKey.jks"

با اجرای دستور فوق، رمزی که هنگام ساخت امضاء تعیین کرده بودم دریافت می‌شود که آنرا وارد کرده و enter می‌زنم. دقت کنید هنگام تایپ رمز عبور در cmd کاراکترها دیده نمی‌شود:

مشاهده می‌کنید اطلاعات کلید ازجمله SHA1 در خط فرمان چاپ شد.
حالا وارد کنسول گوگل شده و در قسمت Credentials کلیدی که قبلا ساختم را ویرایش می‌کنم:

در قسمت Application restrictions گزینه Android apps را انتخاب کرده و سپس روی ADD AN ITEM در قسمت Restrict usage to your Android apps کلیک کردم. در مرحله بعد دو فیلد Package name و SHA-1 certificate fingerprint را تکمیل می‌کنم. در نهایت تغییرات را باید SAVE کنم.
با انجام این تغییرات، اپلیکیشن release شده امکان استفاده از این API را خواهد داشت.

نکته: دستورات keytool در سیستم عامل‌های Linux و MAC یک تفاوت جزئی دارد. لطفا در وب جستجو کنید.

موفق و پیروز باشید.

مطالعه‌ی بیشتر:

https://developers.google.com/android/reference/com/google/android/gms/maps/SupportMapFragment
https://developers.google.com/android/reference/com/google/android/gms/maps/OnMapReadyCallback
https://developers.google.com/android/reference/com/google/android/gms/maps/MapFragment.html
https://developers.google.com/android/reference/com/google/android/gms/maps/GoogleMap.html
https://developers.google.com/android/reference/com/google/android/gms/maps/model/LatLng
https://developers.google.com/android/reference/com/google/android/gms/maps/CameraUpdateFactory.html

توجه : سورس پروژه درون پوشه Exercises قرار دارد

نوشته نمایش نقشه Google Map در اندروید اولین بار در اندروید استودیو پدیدار شد.

در این قسمت از سری مباحث برنامه نویسی اندروید به نحوه کار با Camera2 API جهت اتصال مستقیم به سخت افزار دوربین اندروید و ذخیره تصویر روی حافظه دیوایس می‌پردازیم.

این جلسه در قالب PDF و در ۵۰ صفحه تهیه شده که در ادامه چند صفحه‌ ابتدایی را مشاهده می‌کنید:

در جلسه قبل (آموزش کار با دوربین در برنامه نویسی اندروید) به نحوه کار با دوربین و گرفتن عکس از طریق برنامه داخلی مانند برنامه پیش فرض دوربین پرداختیم. به صورتی که کاربر برای استفاده از دوربین و ثبت تصویر، ابتدا به یک برنامه مدیریت دوربین منتقل شده و سپس نتیجه آن به اپلیکیشن اصلی برگردانده می‌شد.
در این قسمت از مباحث آموزش برنامه نویسی اندروید به آموزش کار با دوربین توسط Camera2 API می‌پردازیم. با بکارگیری API دوربین سیستم عامل اندروید، اتصال به دوربین دیوایس اندرویدی به صورت مستقیم و بدون نیاز به برنامه جانبی امکان پذیر بوده و کاربر برای ثبت تصویر یا ویدئو از محیط برنامه اصلی خارج نمی‌گردد.

معرفی Camera2 API اندروید

در گذشته و تا قبل از معرفی اندروید ۵ یعنی Lollipop یا به عبارتی API 21، توسعه دهندگان اندروید برای ارتباط با دوربین دیوایس‌های اندرویدی در برنامه خود از Camera API استفاده می‌کردند. همزمان با معرفی اندروید ۵ در سال ۲۰۱۴، گوگل از API جدید خود به جهت ارتباط با دوربین رونمایی کرد که Camera2 API نام دارد.
Camera API در حال حاضر Deprecate (منقضی) شده و حتی در نسخه‌های اخیر اندروید به درستی پشتیبانی نمی‌شود. بنابراین لازم است از نسل جدید آن یعنی Camera2 API در پروژه‌های اندرویدی خود استفاده کنیم.

مزایای Camera2 API نسبت به Camera API

نسخه جدید این API مزایایی نسبت به نسل قبل دارد که به تعدادی از مهمترین آنها اشاره می‌کنم:

• با سخت افزار جدید سازگاری بهتری داشته و در نتیجه شاهد خروجی بهینه‌تر و با کیفیت بالاتری هستیم.
• ثبت تصاویر با سرعت بالاتری انجام می‌شود.
• تعدادی افکت (Effect) و فیلتر (Filter) را به صورت مستقیم روی دوربین می‌توان اعمال کرد.
• بدست آوردن لیست دوربین‌های موجود توسط متد getCameraIdList.
• بدست آوردن مشخصات، ویژگی‌ها و تنظیمات (ازجمله رزولوشن) هریک از دوربین‌های موجود توسط متد CameraCharacteristics و استفاده از آنها بر اساس مشخصات دریافتی، جهت حصول بهترین نتیجه. به عبارتی در این نسخه، کنترل بهتری روی دوربین‌ها داریم.

پروژه کار با دوربین و ذخیره عکس روی حافظه دیوایس اندرویدی

در این قسمت، پروژه‌ای را تمرین و بررسی می‌کنیم که در ساده‌ترین حالت ممکن، اَپ ما به صورت مستقیم و از طریق Camera2 API با دوربین گوشی یا تبلت اندرویدی ارتباط برقرار کرده و با زدن یک دکمه، تصویر موردنظر روی حافظه داخلی دیوایس ذخیره می‌گردد. سایر امکانات موجود در API را در آموزش‌های آتی و همچنین در قالب پروژه‌های کاربردی به صورت کاملتر بررسی خواهیم کرد.
یک پروژه جدید اندرویدی با نام Camera2 API در اندروید استودیو با یک Empty Activity و Minimum API 21 ایجاد می‌کنم. من با زبان جاوا کار می‌کنم بنابراین در قسمت زبان، گزینه Java را انتخاب می‌کنم.
در اولین قدم باید Permission یا مجوزهای موردنیاز برای اپلیکیشن اندرویدی خود را در مانیفست پروژه تعریف کنیم. برخلاف پروژه قسمت قبل که برای ثبت تصویر از یک برنامه واسط استفاده کردیم و نیازی به تعیین مجوز نبود، در این پروژه ما به طور مستقیم و توسط API با سخت افزار دوربین سروکار داریم بنابراین لازم است ابتدا مجوز مربوطه از کاربر گرفته شود، در غیر اینصورت سیستم عامل اندروید حق دسترسی به دوربین و کارت حافظه را در اختیار برنامه ما قرار نخواهد داد.

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.hardware.camera2.full" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

سه مجوز فوق را به مانیفست پروژه اضافه کردم. دو مورد نخست جهت دسترسی به دوربین (CAMERA) و مورد سوم مربوط به دریافت مجوز دسترسی به حافظه دیوایس جهت ذخیره سازی تصویر دریافتی از دوربین می‌باشد. WRITE EXTERNAL STORAGE به معنی “نوشتن روی حافظه ذخیره سازی” است.
قبلا در مطلب مربوط به معرفی تگ uses-feature در اندروید پرداختیم. گفتیم از این تگ برای فیلتر اپلیکیشن‌ها در فروشگاه Google Play استفاده می‌شود. فرض را بر این می‌گذاریم که کار با دوربین جزء قابلیت‌های اصلی برنامه ماست و بدون آن، عملکردش با اختلال مواجه می‌گردد. بنابراین برنامه ما در فروشگاه گوگل پلی فقط به کاربرانی باید نمایش داده شود که دیوایس‌شان دارای حداقل یک دوربین باشد. در غیر اینصورت و بعد از نصب برنامه، امکان بهره مندی از اپ ما را نخواهند داشت. لذا تگ زیر را نیز به مانیفست اضافه می‌کنم:

فایل نهایی AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="ir.android_studio.camera2api">

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.hardware.camera2.full" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-feature android:name="android.hardware.camera" android:required="true" />
    
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

سپس layout اکتیویتی را به صورتی ویرایش می‌کنم که شامل یک View برای نمایش دوربین و یک Button برای ثبت تصویر باشد. برای نمایش محتوای دریافتی از دوربین یا به اصطلاح Camera Preview از TextureView استفاده می‌کنیم. از TextureView برای نمایش محتواهایی مانند ویدئو، ویدئوی زنده (Stream) و سایر موارد مشابه بکار می‌رود که در اینجا برای نمایش خروجی دوربین از آن استفاده می‌کنیم:

activity_main.xml:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <TextureView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_alignParentTop="true"
        android:layout_alignParentStart="true"
        android:id="@+id/texture_view"/>

    <Button
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_alignParentBottom="true"
        android:layout_centerHorizontal="true"
        android:id="@+id/capture_btn"
        android:text="Capture" />

</RelativeLayout>

در این پروژه من به تولبار نیازی ندارم و ترجیح می‌دهم آنرا غیر فعال کنم تا TextureView بخش بیشتری از صفحه نمایش را اشغال کند. بنابراین استایل تم پیش فرض را به NoActionBar تغییر می‌دهم:
styles.xml:

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="colorPrimary">@color/colorPrimary</item>
    <item name="colorPrimaryDark">@color/colorPrimaryDark</item>
    <item name="colorAccent">@color/colorAccent</item>
</style>

خب! حالا نوبت به اکتیویتی می‌رسد. ابتدا متدهای موردنیاز را درون بدنه اصلی کلاس MainActivity تعریف می‌کنم:

package ir.android_studio.camera2api;

import androidx.appcompat.app.AppCompatActivity;

import android.hardware.camera2.CameraCaptureSession;
import android.hardware.camera2.CameraDevice;
import android.hardware.camera2.CaptureRequest;
import android.media.ImageReader;
import android.os.Bundle;
import android.os.Handler;
import android.os.HandlerThread;
import android.util.Size;
import android.util.SparseIntArray;
import android.view.Surface;
import android.view.TextureView;
import android.widget.Button;

import java.io.File;

public class MainActivity extends AppCompatActivity {

    private TextureView mTextureView;
    private Button captureButton;
    private static final SparseIntArray ORIENTATION = new SparseIntArray();

    static {
        ORIENTATION.append(Surface.ROTATION_0, 90);
        ORIENTATION.append(Surface.ROTATION_90, 0);
        ORIENTATION.append(Surface.ROTATION_180, 270);
        ORIENTATION.append(Surface.ROTATION_270, 180);
    }

    private String cameraId;
    private CameraDevice camDevice;
    private CameraCaptureSession camCapSession;
    private CaptureRequest capRequest;
    private CaptureRequest.Builder capRequestBuilder;
    private Size imgDimentions;
    private ImageReader imgReader;
    private File picFile;
    private Handler backgroundHandler;
    private HandlerThread backgroundThread;
    private static final int camPermissionReqCode = 200;


    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        mTextureView = findViewById(R.id.texture_view);
        captureButton = findViewById(R.id.capture_btn);

    }
}

نترسید! خط به خط کدها را در ادامه آموزش توضیح می‌دهم.
ابتدا دو ویجت TextureView و Button که در layout قرار دارند را درون متد onCreate تعریف کرده‌ام.
برای برقراری ارتباط بین دوربین و TextureView نیاز به یک شنونده (Listener) دارم. درون بدنه اصلی کلاس اکتیویتی یک متد از نوع TextureView.SurfaceTextureListener با نام دلخواه textureListener اضافه می‌کنم:

متد به صورت زیر توسط اندروید استودیو ساخته می‌شود:

TextureView.SurfaceTextureListener textureListener = new TextureView.SurfaceTextureListener() {
    @Override
    public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int i, int i1) {
        
    }

    @Override
    public void onSurfaceTextureSizeChanged(SurfaceTexture surfaceTexture, int i, int i1) {

    }

    @Override
    public boolean onSurfaceTextureDestroyed(SurfaceTexture surfaceTexture) {
        return false;
    }

    @Override
    public void onSurfaceTextureUpdated(SurfaceTexture surfaceTexture) {

    }
};

این متد ۴ تابع با نام‌های onSurfaceTextureAvailable، onSurfaceTextureSizeChanged، onSurfaceTextureDestroyed و onSurfaceTextureUpdated دارد که کاربرد هرکدام از آنها از نحوه نامگذاری مشخص می‌شود. واژه Available در متد onSurfaceTextureAvailable به معنی “در دسترس” است لذا این متد زمانی اجرا خواهد شد که TextureView در حال اجرا باشد. یعنی زمانی که اکتیویتی حاوی TextureView مدنظر ما اجرا شد، این متد صدا زده می‌شود.

گفتیم با اجرای اکتیویتی و در دسترس قرار گرفتن TextureView متد onSurfaceTextureAvailable هم اجرا می‌شود. بنابراین در این لحظه لازم است دوربین فعال شده و محتوای دریافتی از آن (همان پیش نمایش) به آن ارسال گردد تا کاربر خروجی دوربین را مشاهده نماید. لذا یک متد با نام دلخواه openTheCamera به این تابع اضافه کرده و کدهای مربوط به دریافت اطلاعات دوربین را درون آن می‌نویسم:

public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int i, int i1) {
    openTheCamera();
}

برای ساخت متد بجای نوشتن دستی آن، کافیست در حالی که نشانگر موس روی نام این تابع هست دکمه‌های alt + Enter را زده و روی گزینه create method کلیک کنیم:

در مرحله بعد روی گزینه همنام با اکتیویتی یعنی MainActivity را انتخاب می‌کنم تا متد درون بدنه اصلی کلاس ساخته شود:

به اینصورت متد openTheCamera درون کلاس اکتیویتی و بعد از متد TextureView.SurfaceTextureListener اضافه می‌شود:

TextureView.SurfaceTextureListener textureListener = new TextureView.SurfaceTextureListener() {
    @Override
    public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int i, int i1) {
        openTheCamera();
    }

    @Override
    public void onSurfaceTextureSizeChanged(SurfaceTexture surfaceTexture, int i, int i1) {

    }

    @Override
    public boolean onSurfaceTextureDestroyed(SurfaceTexture surfaceTexture) {
        return false;
    }

    @Override
    public void onSurfaceTextureUpdated(SurfaceTexture surfaceTexture) {

    }
};

private void openTheCamera() {
}

قبل از ادامه کار کد کامل اکتیویتی را قرار می‌دهم تا درک بهتری از وضعیت فعلی اکتیویتی داشته باشید:

package ir.android_studio.camera2api;

import androidx.appcompat.app.AppCompatActivity;

import android.graphics.SurfaceTexture;
import android.hardware.camera2.CameraCaptureSession;
import android.hardware.camera2.CameraDevice;
import android.hardware.camera2.CaptureRequest;
import android.media.ImageReader;
import android.os.Bundle;
import android.os.Handler;
import android.os.HandlerThread;
import android.util.Size;
import android.util.SparseIntArray;
import android.view.Surface;
import android.view.TextureView;
import android.view.View;
import android.widget.Button;

import java.io.File;

public class MainActivity extends AppCompatActivity {

    private TextureView mTextureView;
    private Button captureButton;
    private static final SparseIntArray ORIENTATION = new SparseIntArray();

    static {
        ORIENTATION.append(Surface.ROTATION_0, 90);
        ORIENTATION.append(Surface.ROTATION_90, 0);
        ORIENTATION.append(Surface.ROTATION_180, 270);
        ORIENTATION.append(Surface.ROTATION_270, 180);
    }

    private String cameraId;
    private CameraDevice camDevice;
    private CameraCaptureSession camCapSession;
    private CaptureRequest capRequest;
    private CaptureRequest.Builder capRequestBuilder;
    private Size imgDimentions;
    private ImageReader imgReader;
    private File picFile;
    private Handler backgroundHandler;
    private HandlerThread backgroundThread;
    private static final int camPermissionReqCode = 200;


    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        mTextureView = findViewById(R.id.texture_view);
        captureButton = findViewById(R.id.capture_btn);

    }

    TextureView.SurfaceTextureListener textureListener = new TextureView.SurfaceTextureListener() {
        @Override
        public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int i, int i1) {
            openTheCamera();
        }

        @Override
        public void onSurfaceTextureSizeChanged(SurfaceTexture surfaceTexture, int i, int i1) {

        }

        @Override
        public boolean onSurfaceTextureDestroyed(SurfaceTexture surfaceTexture) {
            return false;
        }

        @Override
        public void onSurfaceTextureUpdated(SurfaceTexture surfaceTexture) {

        }
    };

    private void openTheCamera() {
    }

}

متد openTheCamera را به صورت زیر تکمیل کردم:

private void openTheCamera() {

    CameraManager camManager = (CameraManager) getSystemService(Context.CAMERA_SERVICE);
    cameraId = camManager.getCameraIdList() [0];
    CameraCharacteristics camCharacteristics = camManager.getCameraCharacteristics(cameraId);
    StreamConfigurationMap streamMap = camCharacteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);
    imgDimentions = streamMap.getOutputSizes(SurfaceTexture.class) [0];

    if (ActivityCompat.checkSelfPermission(this, Manifest.permission.CAMERA) != PackageManager.PERMISSION_GRANTED
            && ActivityCompat.checkSelfPermission(this, Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {
        ActivityCompat.requestPermissions(MainActivity.this, new String[] {Manifest.permission.CAMERA, Manifest.permission.WRITE_EXTERNAL_STORAGE}, camPermissionReqCode);
        return;

    }

    camManager.openCamera(cameraId, camStateCallback, null);

}

در خط اول یک شیء از کلاس CameraManager با نام camManager ساختم. این کلاس برای مدیریت دوربین‌ها استفاده می‌گردد. در خط بعد متد getCameraIdList را مشاهده می‌کنید. توسط این متد، لیست شناسه (ID) دوربین(های) موجود در دیوایس برگردانده می‌شود. من می‌خواهم صرفا از دوربین اصلی استفاده شود بنابراین مقدار [۰] را تعریف کرده‌ام. بنابراین دوربین اصلی در متغیر cameraId قرار می‌گیرد.
در ابتدای مبحث عرض کردم در Camera2 API می‌توان مشخصات و جزئیات مربوط به هر دوربین را دریافت کرد. در ادامه و با استفاده از کلاس CameraCharacteristics مربوط به API، مشخصات دوربین اصلی یعنی دوربینی که شناسه آن در cameraId ذخیره شده در camCharacteristics قرار می‌گیرد.
در ادامه به StreamConfigurationMap نیاز داریم تا بوسیله آن بتوان محتوا یا فریم‌های دریافتی از دوربین (به عبارتی محتوای استریم شده از دوربین) را جهت ثبت عکس موردنظر ذخیره کرد.
ما باید اندازه تصویر دریافتی از دوربین را هم داشته باشیم. در خط بعد توسط getOutputSizes سایز خروجی دوربین اصلی (۰) دریافت شده و در متغیر imgDimentions که از نوع Size تعریف شده بود ذخیره می‌گردد.
از اندروید Marshmallow یا همان اندروید ۶ (API 21) به بعد، یک قابلیت امنیتی به نام Runtime Permission اضافه شد که دسترسی به قابلیت‌هایی مانند دوربین، خواندن و نوشتن روی کارت حافظه و… را به وسیله متد requestPermissions هنگام اجرای اپلیکیشن از کاربر می‌گیرد و شخص حق انتخاب و تایید یا عدم تایید هرکدام از موارد را به صورت جداگانه دارد. بر خلاف روال گذشته که تمامی مجوزها قبل از نصب اپ نمایش داده می‌شد و کاربر یا ملزم به پذیرش همه موارد بود تا بتواند فرایند نصب برنامه را ادامه دهد یا باید به کلی از نصب برنامه منصرف می‌شد. این قابلیت به طور مفصل در مطلب آموزش Runtime Permission در اندروید معرفی شده است.

در نهایت با استفاده از متد openCamera ارتباط با دوربین مدنظر برقرار می‌گردد. این متد سه پارامتر دارد. مورد اول شناسه دوربین که آنرا در cameraId ذخیره کردم، مورد دوم یک StateCallBack جهت دریافت وضعیت دوربین و مورد سوم یک کنترل کننده است که در اینجا مقدار null گرفته.
صرفا با توجه به نحوه نامگذاری متدها و کلاس‌ها، تا حدود زیادی نوع کاربرد مشخص می‌شود. state به معنی “وضعیت” و callback به معنی “پاسخ به تماس” است.

بنابراین می‌توان نتیجه گرفت که این متد قرار است وضعیت فعلی دوربین را برگرداند.
برای پارامتر دوم نام دلخواه camStateCallback را تعریف کردم و در ادامه، متد مربوط به آن را به اکتیویتی اضافه خواهم کرد.
در حال حاضر در قسمت getCameraIdList یک ارور وجود دارد:

در اینجا یک استثناء کنترل نشده (Unhandled exception) داریم. این استثناء شامل دو حالت است:
۱- هنگامی که CameraManager نتواند دوربین را باز کند.
۲- هنگامی که ارتباط بین برنامه و دوربین به هردلیل قطع شده و ادامه اتصال ممکن نیست.
برای مدیریت یا به اصطلاح Handle کردن این استثناء، نشانگر موس را روی getCameraIdList قرار داده و کلیدهای alt + Enter را می‌زنم:

دو راه برای هندل کردن این استثناء وجود دارد. با انتخاب گزینه اول یعنی Add exception to method signature استثناء CameraAccessException در عنوان متد تعریف می‌شود:
private void openTheCamera() throws CameraAccessException {}

یا اینکه با انتخاب گزینه دوم و قراردادن getCameraIdList در یک try catch نیز می‌توان مدیریت استثناء احتمالی را انجام داد. من گزینه اول را انتخاب می‌کنم.
این ارور در متد onSurfaceTextureAvailable که openTheCamera را تعریف کردم نیز وجود دارد. مشابه قسمت قبل، با کلیدهای alt + Enter و انتخاب تنها گزینه موجود یعنی Surround with try/catch، متد را به صورت خودکار و بدون نیاز به نوشتن دستی درون یک دستور try catch قرار می‌دهم:

نتیجه:

public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int i, int i1) {
    try {
        openTheCamera();
    } catch (CameraAccessException e) {
        e.printStackTrace();
    }
}

حالا نوبت ساخت پارامتر دوم openCamera یعنی camStateCallback است. یک متد با همین نام و از جنس CameraDevice.StateCallback قبل از متد openTheCamera به کلاس اکتیویتی اضافه می‌کنم:

کلاس CameraDevice برای پردازشِ عکسِ گرفته شده استفاده می‌گردد.
متد به اینصورت ساخته می‌شود:

private final CameraDevice.StateCallback camStateCallback = new CameraDevice.StateCallback() {
    @Override
    public void onOpened(@NonNull CameraDevice cameraDevice) {

    }

    @Override
    public void onDisconnected(@NonNull CameraDevice cameraDevice) {

    }

    @Override
    public void onError(@NonNull CameraDevice cameraDevice, int i) {

    }
};

به نامگذاری توابع درون این متد دقت کنید. در اینجا سه وضعیت دوربین را باید مدیریت کنیم:

• onOpened: هنگامی که اتصال برقرار بوده و دوربین باز است.
• onDisconnected: هنگامی که ارتباط با دوربین قطع شده.
• onError: هنگامی که اروری دریافت می‌شود.

camStateCallBack را به صورت زیر تکمیل می‌کنم:

private final CameraDevice.StateCallback camStateCallback = new CameraDevice.StateCallback() {
    @Override
    public void onOpened(@NonNull CameraDevice cameraDevice) {
        camDevice = cameraDevice;
        createCameraPreview();
    }

    @Override
    public void onDisconnected(@NonNull CameraDevice cameraDevice) {
        camDevice.close();
    }

    @Override
    public void onError(@NonNull CameraDevice cameraDevice, int i) {
        camDevice.close();
        camDevice = null;
    }
};

متد onOpened یک پارامتر از جنس CameraDevice و با نام cameraDevice دارد. camDevice ای که قبلا در اکتیویتی تعریف کردم را برابر این پارامتر قرار دادم. برای ساخت پیش نمایش دوربین و انتقال آن به TextureView نیاز به چند خط کد دیگر داریم. بنابراین یک متد به onOpened اضافه می‌کنم که نام آن را createCameraPreview انتخاب کرده‌ام.
برای onDisconnected و onError توسط متد close ارتباط با دوربین را کامل قطع کردم.
برای ساخت متد createCameraPreview مانند قبل روی آن alt + Enter، انتخاب گزینه create method… و در مرحله بعد انتخاب گزینه MainActivity تا متد درون کلاس ایجاد شود:

private void createCameraPreview() {}

متد را به اینصورت کامل می‌کنم:

private void createCameraPreview() {

    SurfaceTexture surTexure = mTextureView.getSurfaceTexture();
    surTexure.setDefaultBufferSize(imgDimentions.getWidth(), imgDimentions.getHeight());
    Surface mSurface = new Surface(surTexure);
    capRequestBuilder = camDevice.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);
    capRequestBuilder.addTarget(mSurface);

    camDevice.createCaptureSession(Arrays.asList(mSurface), new CameraCaptureSession.StateCallback() {
        @Override
        public void onConfigured(@NonNull CameraCaptureSession cameraCaptureSession) {

            if (camDevice == null) {
                return;
            }

            camCapSession = cameraCaptureSession;
            updatePreview();

        }

        @Override
        public void onConfigureFailed(@NonNull CameraCaptureSession cameraCaptureSession) {

            Toast.makeText(MainActivity.this, "Configuration cannot be completed!", Toast.LENGTH_SHORT).show();
            
        }
    }, null);

}

در خط اول از متد SurfaceTexture یک شیء با نام surTexure ساختم. این متد داده‌های دریافتی از متد Surface را به فریم‌های قابل نمایش در TextureView تبدیل کرده و به آن ارسال می‌کند.
در خط بعد اندازه پیش فرض تصویر دریافتی به واسطه متد setDefaultBufferSize تنظیم می‌شود. یعنی عرض (getWidth) و ارتفاع آن (getHeight).
در ادامه از متد Surface یک شیء با نام mSurface ساختم که بافرهای خام دریافتی از دوربین را توسط OpenGL ES پردازش کرده و از طریق SurfaceTexture به ویجت TextureView ارسال می‌کند.
قبلا در بدنه اکتیویتی یک CaptureRequest.Builder با نام capRequestBuilder تعریف کرده بودم. از این متد برای ساخت “درخواست گرفتن عکس” استفاده می‌شود. در اینجا درخواستی ارسال می‌گردد که مناسب قالب پیش نمایش دوربین یعنی TEMPLATE_PREVIEW باشد.
در خط بعد توسط addTarget نمایه مدنظر یعنی mSurface را به لیست هدف‌های این درخواست (Request) اضافه می‌کنیم.
سپس توسط متد createCaptureSession وضعیت “گرفتن عکس” را بررسی می‌کنیم. به دلیل پیکربندی دوربین و همچنین اختصاص بافر حافظه جهت ارسال تصویر به مقصد موردنظر، ایجاد یک session سنگین بوده و ممکن است زمان زیادی (حدود چندصد میلی ثانیه) طول بکشد.
متد را به اینصورت در createCameraPreview تعریف می‌کنم:

بعد از اضافه شدن پارامتر دوم یعنی StateCallback، خطایی گرفته می‌شود که لازم است پارامتر سوم هم تعریف شود. مطابق کد زیر پارامتر سوم null تعریف شده:

camDevice.createCaptureSession(Arrays.asList(mSurface), new CameraCaptureSession.StateCallback() {
    @Override
    public void onConfigured(@NonNull CameraCaptureSession cameraCaptureSession) {

    }

    @Override
    public void onConfigureFailed(@NonNull CameraCaptureSession cameraCaptureSession) {

    }
}, null);

جهت مطالعه ادامه آموزش، فایل PDF را دانلود نمائید

توجه : سورس پروژه درون پوشه Exercises قرار دارد

با توجه به اینکه آموزش‌های پایه با قیمت پایین در اختیار کاربر قرار گرفته و درآمد حاصل صرف تامین هزینه‌های وب سایت و تهیه آموزش‌های آتی می‌شود، به اشتراک گذاری این فایل با دیگران خلاف اخلاق است.

نوشته کار با دوربین در اندروید توسط Camera۲ API اولین بار در اندروید استودیو پدیدار شد.