WinToast
v1.3.0
Wintoast هي مكتبة خفيفة مكتوبة في C ++ والتي تجلب تكاملًا كاملاً لإشعارات الخبز المحمص الحديث لنظام التشغيل Windows 8 و Windows 10 و Windows 11 .
تتيح إخطارات Toast لتطبيقك إبلاغ المستخدمين بالمعلومات ذات الصلة والأحداث في الوقت المناسب التي يجب عليهم رؤيتها واتخاذ الإجراءات عليها داخل تطبيقك ، مثل رسالة فورية جديدة أو طلب صداقة جديد أو أخبار عاجلة أو حدث تقويمي.
يدمج Wintoast جميع القوالب القياسية المتاحة في تعداد ToastTemplateType.
| نموذج | وصف | مثال |
|---|---|---|
ImageAndText01 | صورة كبيرة وسلسلة واحدة ملفوفة عبر ثلاثة أسطر من النص. |  |
ImageAndText02 | صورة كبيرة ، سلسلة واحدة من النص الغامق على السطر الأول ، سلسلة واحدة من النص العادي ملفوفة عبر الأسطر الثانية والثالثة. |  |
ImageAndText03 | صورة كبيرة ، سلسلة واحدة من النص الجريء ملفوفة عبر الخطين الأولين ، سلسلة واحدة من النص العادي على السطر الثالث. |  |
ImageAndText04 | صورة كبيرة ، سلسلة واحدة من النص الغامق على السطر الأول ، سلسلة واحدة من النص العادي على السطر الثاني ، سلسلة واحدة من النص العادي على السطر الثالث. |  |
Text01 | سلسلة واحدة ملفوفة عبر ثلاثة أسطر من النص. |  |
Text02 | سلسلة واحدة من النص الجريء على السطر الأول ، سلسلة واحدة من النص العادي ملفوفة عبر الأسطر الثانية والثالثة. |  |
Text03 | سلسلة واحدة من النص الجريء ملفوفة عبر الخطين الأولين ، سلسلة واحدة من النص العادي على السطر الثالث. |  |
Text04 | سلسلة واحدة من النص الغامق على السطر الأول ، سلسلة واحدة من النص العادي على السطر الثاني ، سلسلة واحدة من النص العادي على السطر الثالث. |  |
مثال على قالب ImageAndText02 :
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" title " , WinToastTemplate::FirstLine);
templ.setTextField( L" subtitle " , WinToastTemplate::SecondLine);
templ.setImagePath( L" C:/example.png " ); ملاحظة: يمكن للمستخدم استخدام صوت النظام الافتراضي أو تحديد صوت لتشغيله عند عرض إشعار الخبز المحمص. نفس السلوك لصورة إخطار الخبز المحمص ، يحاول Windows افتراضيًا استخدام أيقونة التطبيق.*
Wintoast التعامل مع الأحداث المختلفة:
أنشئ معالجك المخصص للتفاعل مع إجراءات المستخدم عن طريق التصنيف الفرعي للواجهة IWinToastHandler :
class WinToastHandlerExample : public IWinToastHandler {
public:
WinToastHandlerExample ();
// Public interfaces
void toastActivated () const override ;
void toastActivated ( int actionIndex) const override ;
void toastDismissed (WinToastDismissalReason state) const override ;
void toastFailed () const override ;
};الوثائق الكاملة لمحتوى الإخطار هنا.
لإنشاء إشعارات مهمة ، الإنذارات ، التذكيرات ، وإخطارات المكالمات الواردة ، يمكنك ببساطة استخدام إشعار التطبيق العادي مع قيمة سيناريو مخصصة لها. يقوم السيناريو بضبط بعض السلوكيات لإنشاء تجربة مستخدم متسقة وموحدة. هناك أربع قيم سيناريو محتملة:
حدد الوقت الذي لم يعد فيه إشعار الخبز المحمص حاليًا أو صالحًا ولا ينبغي عرضه. يحاول Windows رفع إشعارات الخبز المحمص فورًا بعد الاتصال ، لذلك نادراً ما يتم استخدام هذه الخاصية.
بالنسبة لتطبيق Windows 8.x ، تتسبب هذه الخاصية أيضًا في إزالة إشعار الخبز المحمص من مركز الإجراءات بمجرد الوصول إلى البيانات المحددة والوقت.
ملاحظة: سلوك Windows الافتراضي هو إخفاء الإخطار تلقائيًا بعد تعيين الوقت في إعدادات Windows Ease of Access. إذا كنت بحاجة إلى الحفاظ على الإخطار في مركز عمل Windows لفترة أطول من الوقت ، فيجب عليك الاتصال بـ WinToastTemplate::setExpiration .
توصي إرشادات نمط Microsoft بتمثيل صور الملف الشخصي مع صورة دائرية لتوفير تمثيل ثابت للأشخاص عبر التطبيقات والقذيفة. اضبط خاصية Hintcrop على دائرة لتوفير الصورة بمحصول دائري.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" Matt sent you a friend request " , WinToastTemplate::FirstLine);
templ.setTextField( L" Hey, wanna dress up as wizards and ride around on hoverboards? " , WinToastTemplate::SecondLine);
templ.setImagePath( L" C:/example.png " );
templ.setHintCrop(WinToastTemplate::Circle);
صورة البطل هي صورة كبيرة تظهر في الجزء العلوي من إخطار الخبز المحمص. صورة البطل اختيارية ويمكن استخدامها لتوفير سياق إضافي للمستخدم.
ملاحظة: لا يتم دعم صورة Hero على Windows 8.1 و Windows Phone 8.1.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setTextField( L" Mary Anne " , WinToastTemplate::FirstLine);
templ.setTextField( L" Check out where we camped last night! " , WinToastTemplate::SecondLine);
templ.setHeroImagePath( L" C:/example.png " );
يتم تحديد صورة البطل من خلال استدعاء طريقة WinToastTemplate::setHeroImagePath . يمكن أن يكون مسار الصورة مسارًا محليًا للملف أو URI.
المعلمة الثانية للطريقة WinToastTemplate::setHeroImagePath هي قيمة منطقية تحدد ما إذا كان ينبغي أن تكون الصورة محددة في إشعار الخبز المحمص.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);
templ.setTextField( L" Feature image of the day " , WinToastTemplate::FirstLine);
templ.setHeroImagePath( L" C:/example.png " , true );
يمكنك إضافة إجراءاتك الخاصة ، هذه الحقيقة تسمح لك بالتفاعل مع المستخدم بطريقة مختلفة:
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText01);
templ.setTextField( L" New product in stock " , WinToastTemplate::FirstLine);
std::vector<std::wstring> actions;
actions.push_back( L" See more details " );
actions.push_back( L" Remind me later " );
// ...
for ( auto const &action : actions) {
templ. addAction (action);
}
WinToast::instance ()->showToast(templ, handler) 
جديد في تحديث الذكرى السنوية: إذا كنت بحاجة إلى الرجوع إلى مصدر المحتوى الخاص بك ، فيمكنك استخدام نص الإسناد. يتم عرض هذا النص دائمًا أسفل أي عناصر نصية ، ولكن فوق الصور المضمنة. يستخدم النص حجمًا أصغر قليلاً من العناصر النصية القياسية للمساعدة في التمييز بين العناصر النصية العادية.
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::Text02);
templ.setTextField( L" Mary Anne " , WinToastTemplate::FirstLine);
templ.setTextField( L" Check out where we camped last night! " , WinToastTemplate::SecondLine);
templ.setHeroImagePath( L" C:/example.png " );
templ.setAttributionText( L" Via SMS " );
مقدار الوقت الذي يجب أن يعرضه الخبز المحمص. يمكن أن تحتوي هذه السمة على واحدة من القيم التالية: - النظام : تكوين النظام الافتراضي. - قصير : تكوين الوقت الافتراضي للوقت القصير. - طويل : تكوين النظام الافتراضي لفترة طويلة.
يمكنك تعديل السلوكيات المختلفة للصوت: - الافتراضي : يلعب ملف الصوت مرة واحدة فقط. - صامت : قم بإيقاف تشغيل الصوت. - حلقة : تلعب الصوت المعطى في حلقة أثناء وجود الخبز المحمص.
يسمح Wintoast بتعديل ملف الصوت الافتراضي. أضف الملف المحدد إلى موارد المشاريع الخاصة بك ( يجب أن يكون ms-appx: // أو ms-appdata: // path ) وتحديده عن طريق الاتصال:
WinToastTemplate::setAudioPath
بشكل افتراضي ، تتحقق Wintoast إذا كانت أنظمتك تدعم الميزات ، متجاهلة تلك غير المدعومة.
هناك عدة أسباب يمكن أن تفشل Wintoast ولهذا السبب تقوم المكتبة بإخطار المتصل عن سبب فشل. هذه هي الرمز لكل فشل:
| Wintoasterror | رمز الخطأ | رسالة الخطأ |
|---|---|---|
NoError | 0x00 | لا خطأ. تم تنفيذ العملية بشكل صحيح |
NotInitialized | 0x01 | لم تتم تهيئة المكتبة |
SystemNotSupported | 0x02 | نظام التشغيل لا يدعم Wintoast |
ShellLinkNotCreated | 0x03 | لم تتمكن المكتبة من إنشاء رابط قذيفة للتطبيق |
InvalidAppUserModelID | 0x04 | Aumi ليس صالحًا |
InvalidParameters | 0x05 | المعلمات المستخدمة لتكوين المكتبة ليست صالحة بشكل طبيعي لأن اسم AUMI غير صالح أو تطبيق |
NotDisplayed | 0x06 | تم إنشاء الخبز المحمص بشكل صحيح ولكن Wintoast لم يكن قادرًا على عرض الخبز المحمص |
UnknownError | 0x07 | خطأ غير معروف |
مثال شائع للاستخدام هو التحقق مع تهيئة المكتبة أو إظهار إشعار نخب رمز الفشل المحتمل:
WinToast::WinToastError error;
const auto succedded = WinToast::instance()-> initialize (&error);
if (!succedded) {
std::wcout << L" Error, could not initialize the lib. Error number: "
<< error << std::endl;
}
...
// Configure the template
...
const auto toast_id = WinToast::instance()-> showToast (templ, handler, &error);
if (toast_id < 0 ) {
std::wcout << L" Error: Could not launch your toast notification. Error: "
<< error << std::endl;
}للحصول على سهولة الاستخدام ، يمكنك فقط استخدام مثيل Singleton المتاح.
الخطوة الأولى ، استيراد ملف الرأس wintoastlib.h إلى مشروعك. يجب عليك التحقق مما إذا كان إصدار Windows مدعومًا من قبل المكتبة.
using namespace WinToastLib ;
....
if (!WinToast::isCompatible()) {
std::wcout << L" Error, your system in not supported! " << std::endl;
}قم بتكوين معرف نموذج مستخدم التطبيق الخاص بك ، يمكن القيام بذلك باستخدام المساعد الحالي:
WinToast::instance ()->setAppName( L" WinToastExample " );
const auto aumi = WinToast::configureAUMI( L" mohabouje " , L" wintoast " , L" wintoastexample " , L" 20161006 " );
WinToast::instance ()->setAppUserModelId(aumi); تهيئة جميع التبعيات وتحقق مما إذا كان قد تمت تهيئة Wintoast بنجاح في نظامك:
if (!WinToast::instance()-> initialize ()) {
std::wcout << L" Error, could not initialize the lib! " << std::endl;
} قم بتنفيذ معالج الإجراء الخاص بك عن طريق التصنيف الفرعي للواجهة IWinToastHandler و Custom your your your:
WinToastHandlerExample* handler = new WinToastHandlerExample;
WinToastTemplate templ = WinToastTemplate(WinToastTemplate::ImageAndText02);
templ.setImagePath( L" C:/example.png " );
templ.setTextField( L" title " , WinToastTemplate::FirstLine);
templ.setTextField( L" subtitle " , WinToastTemplate::SecondLine);أظهر أخيرًا النتائج:
const auto toast_id = WinToast::instance()-> showToast (templ, handler, &error);
if (toast_id < 0 ) {
std::wcout << L" Error: Could not launch your toast notification! " << std::endl;
}كتب Shao Voon Wong مقالًا ممتازًا عن استخدام Wintoast. يمكنك العثور عليه هنا.
إذا كنت تستخدم مدير الحزمة ، فهناك منفذ لـ VCPKG. خلاف ذلك ، فإن أسهل طريقة هي نسخ الملفات المصدر كتبعيات خارجية.
يسمح Windows بتكوين السلوك الافتراضي لإعلام الخبز المحمص. يمكن القيام بذلك في سهولة تكوين الوصول عن طريق تعديل علامة تبويب الخيارات الأخرى .
يساعدك تكوين النظام على تحديد المدة التي ترغب في ظهور الإخطارات لمدة 5 ثوان إلى 5 دقائق) كإشعارات مرئية للصوت.
